prometheus-mcp

MCP server for Prometheus metrics and observability. Give Claude (or any MCP-capable agent) read access to your Prometheus instance — query metrics with PromQL, inspect active alerts, and explore scrape targets — without leaving the conversation.

Why another Prometheus MCP?

The existing Prometheus integrations require custom scripts or direct API knowledge. This server:

• Speaks the standard Model Context Protocol over stdio — works with Claude Desktop, Claude Code, Cursor, and any MCP client.
• Is read-only: all 5 tools carry readOnlyHint: true — zero risk of modifying Prometheus data.
• Returns dual-channel output: structured JSON (structuredContent) for programmatic use + Markdown (content) for human-readable display.
• Has actionable error messages that name the exact env var to fix and suggest a next step.
• Supports Bearer token, HTTP Basic auth, or no auth (common for internal deployments).

Tools

Installation

pip install prometheus-mcp

Or run directly without installing:

uvx prometheus-mcp

Configuration

All configuration is via environment variables:

Copy .env.example to .env and fill in your values.

Claude Desktop / Claude Code setup

Add to your MCP config (claude_desktop_config.json or .claude/mcp.json):

{
  "mcpServers": {
    "prometheus": {
      "command": "prometheus-mcp",
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com",
        "PROMETHEUS_TOKEN": "your-token-here"
      }
    }
  }
}

Or with uvx (no install required):

{
  "mcpServers": {
    "prometheus": {
      "command": "uvx",
      "args": ["prometheus-mcp"],
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com"
      }
    }
  }
}

Docker

docker run --rm -e PROMETHEUS_URL=https://prometheus.example.com prometheus-mcp

Example queries

Once configured, ask Claude:

• "What metrics does Prometheus have about HTTP requests?"
• "What is the current request rate for the payment service?"
• "Show me CPU usage over the last hour with 5-minute resolution"
• "Are there any firing alerts? What's their severity?"
• "Which scrape targets are currently down and why?"
• "How many node-exporter instances are up?"

Tool usage guide

prometheus_list_metrics

Returns all metric names Prometheus knows about. Use pattern to filter by substring (case-insensitive). Start here when you don't know which metrics are available. Output is capped at 500 metrics with a truncation hint.

prometheus_query

Execute an instant PromQL expression and get current values. Returns result type (vector/scalar/matrix/string), sample count, and per-sample labels and values.

Parameters:

• query (required) — PromQL expression, e.g. up, rate(http_requests_total[5m])
• time (optional) — RFC3339 or Unix timestamp; defaults to now

prometheus_query_range

Execute a PromQL expression over a time window. Returns one series per matching time series with timestamped values. Total data points across all series are capped at 5000.

Parameters:

• query (required) — PromQL expression
• start / end (required) — RFC3339 or Unix timestamps
• step (required) — resolution like 15s, 1m, 5m

Prometheus rejects steps that would produce > 11,000 points per series (HTTP 422). Increase step or narrow the range if this happens.

Note: The Prometheus range API does not support filtering by branch or commit — filters are expressed purely in PromQL label matchers.

prometheus_list_alerts

Returns all active/pending alerts with labels (including alertname, severity), state, activation time, and current value. Includes a state summary (firing vs pending counts).

prometheus_list_targets

Returns scrape targets with job name, instance address, health (up/down/unknown), last scrape duration in milliseconds, and any error message. Includes a per-job summary. Filter by state: active (default), dropped, or any.

Performance characteristics

• All tools use a single persistent requests.Session with connection pooling.
• The session has trust_env = False to bypass environment proxies (Prometheus is typically an internal service).
• Requests time out after 30 seconds.
• prometheus_query_range caps output at 5000 total points across all series — use a larger step for long windows.
• prometheus_list_metrics returns up to 500 metrics after filtering.

Development

git clone https://github.com/mshegolev/prometheus-mcp
cd prometheus-mcp
pip install -e '.[dev]'
pytest tests/ -v
ruff check src tests
ruff format src tests

License

MIT — see LICENSE.