{
  "markdown": "# prometheus-mcp\n\n<!-- mcp-name: io.github.mshegolev/prometheus-mcp -->\n\n[![PyPI version](https://img.shields.io/pypi/v/prometheus-mcp.svg)](https://pypi.org/project/prometheus-mcp/)\n[![Python versions](https://img.shields.io/pypi/pyversions/prometheus-mcp.svg)](https://pypi.org/project/prometheus-mcp/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Tests](https://github.com/mshegolev/prometheus-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/mshegolev/prometheus-mcp/actions/workflows/test.yml)\n\n**MCP server for [Prometheus](https://prometheus.io/) metrics and observability.**\nGive 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.\n\n## Why another Prometheus MCP?\n\nThe existing Prometheus integrations require custom scripts or direct API knowledge. This server:\n\n- Speaks the standard [Model Context Protocol](https://modelcontextprotocol.io/) over **stdio** — works with Claude Desktop, Claude Code, Cursor, and any MCP client.\n- Is **read-only**: all 5 tools carry `readOnlyHint: true` — zero risk of modifying Prometheus data.\n- Returns **dual-channel output**: structured JSON (`structuredContent`) for programmatic use + Markdown (`content`) for human-readable display.\n- Has **actionable error messages** that name the exact env var to fix and suggest a next step.\n- Supports **Bearer token**, **HTTP Basic auth**, or **no auth** (common for internal deployments).\n\n## Tools\n\n| Tool | Endpoint | Description |\n|------|----------|-------------|\n| `prometheus_list_metrics` | `GET /api/v1/label/__name__/values` | List all metric names with optional substring filter (cap 500) |\n| `prometheus_query` | `GET /api/v1/query` | Execute an instant PromQL query |\n| `prometheus_query_range` | `GET /api/v1/query_range` | Execute a PromQL range query returning time-series |\n| `prometheus_list_alerts` | `GET /api/v1/alerts` | List active and pending alerts |\n| `prometheus_list_targets` | `GET /api/v1/targets` | List scrape targets by health and job |\n\n## v4.0 Advanced Alert Correlation Features\n\nVersion 4.0 introduces powerful new capabilities for AI agents to autonomously investigate production errors:\n\n### Cross-Instance Alert Correlation\n- Automatically identify related alerts across multiple Prometheus instances\n- Group alerts by service identifiers to understand incident scope\n- Detect cascading alert patterns with directional dependency inference\n\n### Root Cause Analysis\n- Anomaly detection in metrics with automatic seasonality adjustment\n- Dependency chain traversal from symptoms to potential root causes\n- Change point detection correlating alerts with recent deployments or config changes\n- Ranked root cause candidates based on evidence strength and impact analysis\n\n### Dependency Mapping & Health\n- Dynamic service dependency maps built from traffic correlation analysis\n- Cross-cluster dependency visualization showing service interoperation\n- Synthetic health probing to assess dependency resilience\n- Load shedding recommendations based on dependency fragility\n\n### Trend Analysis & Benchmarking\n- Historical pattern recognition for recurring alert schedules\n- Capacity forecasting to predict resource exhaustion\n- MTTR benchmarking comparing resolution times against historical data\n- Deviation detection triggering higher-priority notifications for pattern breaks\n\n### Integrated Analysis Tool\n- New `federation_analyze_alerts` tool combining all v4.0 features\n- Unified output format optimized for AI agent consumption\n- Comprehensive incident context in a single tool call\n\n## Installation\n\n```bash\npip install prometheus-mcp\n```\n\nOr run directly without installing:\n\n```bash\nuvx prometheus-mcp\n```\n\n## Configuration\n\nAll configuration is via environment variables:\n\n| Variable | Required | Default | Description |\n|----------|----------|---------|-------------|\n| `PROMETHEUS_URL` | **Yes** | — | Prometheus server URL, e.g. `https://prometheus.example.com` (no trailing slash) |\n| `PROMETHEUS_TOKEN` | No | — | Bearer token (takes precedence over Basic auth) |\n| `PROMETHEUS_USERNAME` | No | — | HTTP Basic auth username |\n| `PROMETHEUS_PASSWORD` | No | — | HTTP Basic auth password |\n| `PROMETHEUS_SSL_VERIFY` | No | `true` | Set `false` for self-signed certificates |\n\nCopy `.env.example` to `.env` and fill in your values.\n\n## Claude Desktop / Claude Code setup\n\nAdd to your MCP config (`claude_desktop_config.json` or `.claude/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"prometheus\": {\n      \"command\": \"prometheus-mcp\",\n      \"env\": {\n        \"PROMETHEUS_URL\": \"https://prometheus.example.com\",\n        \"PROMETHEUS_TOKEN\": \"your-token-here\"\n      }\n    }\n  }\n}\n```\n\nOr with `uvx` (no install required):\n\n```json\n{\n  \"mcpServers\": {\n    \"prometheus\": {\n      \"command\": \"uvx\",\n      \"args\": [\"prometheus-mcp\"],\n      \"env\": {\n        \"PROMETHEUS_URL\": \"https://prometheus.example.com\"\n      }\n    }\n  }\n}\n```\n\n## Docker\n\n```bash\ndocker run --rm -e PROMETHEUS_URL=https://prometheus.example.com prometheus-mcp\n```\n\n## Example queries\n\nOnce configured, ask Claude:\n\n- \"What metrics does Prometheus have about HTTP requests?\"\n- \"What is the current request rate for the payment service?\"\n- \"Show me CPU usage over the last hour with 5-minute resolution\"\n- \"Are there any firing alerts? What's their severity?\"\n- \"Which scrape targets are currently down and why?\"\n- \"How many node-exporter instances are up?\"\n\n## Tool usage guide\n\n### `prometheus_list_metrics`\n\nReturns 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.\n\n### `prometheus_query`\n\nExecute an instant PromQL expression and get current values. Returns result type (vector/scalar/matrix/string), sample count, and per-sample labels and values.\n\nParameters:\n- `query` (required) — PromQL expression, e.g. `up`, `rate(http_requests_total[5m])`\n- `time` (optional) — RFC3339 or Unix timestamp; defaults to now\n\n### `prometheus_query_range`\n\nExecute 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.\n\nParameters:\n- `query` (required) — PromQL expression\n- `start` / `end` (required) — RFC3339 or Unix timestamps\n- `step` (required) — resolution like `15s`, `1m`, `5m`\n\nPrometheus rejects steps that would produce > 11,000 points per series (HTTP 422). Increase step or narrow the range if this happens.\n\n**Note:** The Prometheus range API does not support filtering by branch or commit — filters are expressed purely in PromQL label matchers.\n\n### `prometheus_list_alerts`\n\nReturns all active/pending alerts with labels (including `alertname`, `severity`), state, activation time, and current value. Includes a state summary (firing vs pending counts).\n\n### `prometheus_list_targets`\n\nReturns 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`.\n\n## Performance characteristics\n\n- All tools use a single persistent `requests.Session` with connection pooling.\n- The session has `trust_env = False` to bypass environment proxies (Prometheus is typically an internal service).\n- Requests time out after 30 seconds.\n- `prometheus_query_range` caps output at 5000 total points across all series — use a larger step for long windows.\n- `prometheus_list_metrics` returns up to 500 metrics after filtering.\n\n## Development\n\n```bash\ngit clone https://github.com/mshegolev/prometheus-mcp\ncd prometheus-mcp\npip install -e '.[dev]'\npytest tests/ -v\nruff check src tests\nruff format src tests\n```\n\n## API Specification\n\nThis project includes an OpenAPI 3.0 specification in the `specs/` directory that documents all MCP tools exposed by the server.\n\nTo validate the specification:\n```bash\npython3 specs/validate_spec.py\n```\n\n## Automation\n\nThis repository includes automated scripts and GitHub Actions workflows to streamline the release process:\n\n### Scripts\n\n- `scripts/auto-commit-push.sh` - Automatically commit and push changes with optional release trigger\n- `scripts/release.sh` - Full release automation including pipeline checking, version bumping, and tagging\n\n### GitHub Actions Workflows\n\n- `post-push-check.yml` - Monitors test pipeline status after each push and comments on the commit\n- `auto-release.yml` - Manual workflow to create releases with version bumping (patch, minor, or major)\n\nTo trigger an automated release:\n1. Go to the Actions tab in GitHub\n2. Select \"Auto Release\" workflow\n3. Run the workflow with your preferred version bump type\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 8942,
  "sha": "9da0680e428412dcedbb444c7e704f49c6c1b2509b68042dd1d3bfbaab5ad209",
  "repo_slug": "mshegolev/prometheus-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mshegolev_prometheus_mcp_9758b50a/readme"
}