playbooks

home / mcp / prometheus mcp server

Prometheus MCP Server

Provides MCP access to Prometheus metrics, enabling AI assistants to query PromQL, discover metrics, and inspect targets.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "pab1it0-prometheus-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PROMETHEUS_URL",
        "ghcr.io/pab1it0/prometheus-mcp-server:latest"
      ],
      "env": {
        "PROMETHEUS_URL": "<your-prometheus-url>"
      }
    }
  }
}

You can grant AI assistants access to your Prometheus metrics by running an MCP server that exposes Prometheus data and PromQL queries through standardized MCP interfaces. This enables assistants to query metrics, discover metrics, and analyze data in a structured, interoperable way.

How to use

Use an MCP client to connect to the Prometheus MCP Server. The server exposes tools to run instant and range PromQL queries, discover metrics and metadata, and view target information. Start by launching the server through Docker, then configure your MCP client with the provided connection settings. Once connected, you can execute queries, browse metrics, and inspect results directly from your AI assistant.

How to install

Prerequisites you need before installation:

  • A Prometheus server that is reachable from your environment
  • An MCP-compatible client (for example Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, or another MCP client)

Prerequisites

- Prometheus server accessible from your environment - MCP-compatible client (Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, etc.)

Install via Docker (recommended method)

# Run the MCP server with Docker, supplying your Prometheus URL
docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

Manual Docker setup (explicit examples)

If you prefer to run directly with Docker and customize authentication, use these examples.

# Without authentication
docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

# With basic authentication
docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  -e PROMETHEUS_USERNAME="admin" \
  -e PROMETHEUS_PASSWORD="password" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

Using with Claude Code or other MCP clients

If you are configuring CLI-based MCP clients, set the MCP connection to your server's command and environment. For example, in Claude Code, you would add a new MCP server using a docker run command and define PROMETHEUS_URL as the target Prometheus instance.

Configuration options

Configure how the server connects to Prometheus and how it communicates with MCP clients using environment variables. The essential option is PROMETHEUS_URL which must point to your Prometheus instance. Optional settings control SSL verification, request timeouts, authentication, and MCP transport behavior.

Security and access

Protect access to your Prometheus MCP Server by using authentication options supported by the container: basic authentication via PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD, or a Bearer token via PROMETHEUS_TOKEN. Enforce SSL verification as needed with PROMETHEUS_URL_SSL_VERIFY, and restrict access to trusted networks.

Notes

The server exposes a set of tools that let you perform health checks, run queries, and discover metrics. You can adjust which tools are available to MCP clients according to your needs.

Troubleshooting

If you encounter connection issues, verify that PROMETHEUS_URL is reachable from the host running the MCP server, check your environment variables for typos, and confirm that the Prometheus instance accepts connections from your environment. Review container logs for errors related to authentication, timeouts, or SSL settings.

Examples

Common use cases include executing instant queries, retrieving range query results with specific step intervals, listing available metrics, and obtaining metric metadata or targets information to help you understand your Prometheus deployment.

Available tools

health_check

Health check endpoint for container monitoring and status verification

execute_query

Execute a PromQL instant query against Prometheus

execute_range_query

Execute a PromQL range query with start time, end time, and step interval

list_metrics

List all available metrics in Prometheus with pagination and filtering support

get_metric_metadata

Get metadata for a specific metric

get_targets

Get information about all scrape targets