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).

Related MCP server: prometheus-mcp-server

Tools

v4.0 Advanced Alert Correlation Features

Version 4.0 introduces powerful new capabilities for AI agents to autonomously investigate production errors:

Cross-Instance Alert Correlation

• Automatically identify related alerts across multiple Prometheus instances

• Group alerts by service identifiers to understand incident scope

• Detect cascading alert patterns with directional dependency inference

Root Cause Analysis

• Anomaly detection in metrics with automatic seasonality adjustment

• Dependency chain traversal from symptoms to potential root causes

• Change point detection correlating alerts with recent deployments or config changes

• Ranked root cause candidates based on evidence strength and impact analysis

Dependency Mapping & Health

• Dynamic service dependency maps built from traffic correlation analysis

• Cross-cluster dependency visualization showing service interoperation

• Synthetic health probing to assess dependency resilience

• Load shedding recommendations based on dependency fragility

Trend Analysis & Benchmarking

• Historical pattern recognition for recurring alert schedules

• Capacity forecasting to predict resource exhaustion

• MTTR benchmarking comparing resolution times against historical data

• Deviation detection triggering higher-priority notifications for pattern breaks

Integrated Analysis Tool

• New federation_analyze_alerts tool combining all v4.0 features

• Unified output format optimized for AI agent consumption

• Comprehensive incident context in a single tool call

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

API Specification

This project includes an OpenAPI 3.0 specification in the specs/ directory that documents all MCP tools exposed by the server.

To validate the specification:

python3 specs/validate_spec.py

Automation

This repository includes automated scripts and GitHub Actions workflows to streamline the release process:

Scripts

• scripts/auto-commit-push.sh - Automatically commit and push changes with optional release trigger

• scripts/release.sh - Full release automation including pipeline checking, version bumping, and tagging

GitHub Actions Workflows

• post-push-check.yml - Monitors test pipeline status after each push and comments on the commit

• auto-release.yml - Manual workflow to create releases with version bumping (patch, minor, or major)

To trigger an automated release:

1. Go to the Actions tab in GitHub

2. Select "Auto Release" workflow

3. Run the workflow with your preferred version bump type

License

MIT — see LICENSE.