prom-mcp

prom-mcp — Prometheus MCP Server for AI Agents (Claude Code, Cursor)

prom-mcp is a Prometheus MCP server (Model Context Protocol) that gives AI agents production-grade eyes on your metrics. Connect Claude Code, Cursor, or any MCP client to Prometheus and let the agent run PromQL queries, explain firing alerts with their rule definitions, and discover which series actually exist before querying — so it investigates instead of guessing.

Built by a production engineer who works on-call, so the output reads like a triage note, not a raw JSON dump.

5 tools • 2 resources • 1 triage prompt • single Go binary • zero dependencies • stdio

Install

Claude Desktop (MCPB, no toolchain needed)

Download the bundle for your platform, then open it or drag it into Claude Desktop (Settings → Extensions). You will be asked for your Prometheus URL, which defaults to http://localhost:9090.

Claude Code

With the binary on your PATH (release download or go install, see below):

claude mcp add prom -- prom-mcp

Set PROM_URL in your shell first if your Prometheus is not at http://localhost:9090, or pass --env PROM_URL=... to the command. More variants in examples/claude-code.md.

Cursor

Add to ~/.cursor/mcp.json (same file as examples/cursor-mcp.json):

{
  "mcpServers": {
    "prom": {
      "command": "prom-mcp",
      "env": {
        "PROM_URL": "http://localhost:9090"
      }
    }
  }
}

VS Code

Add to .vscode/mcp.json (same file as examples/vscode-mcp.json):

{
  "servers": {
    "prom": {
      "command": "prom-mcp",
      "env": {
        "PROM_URL": "http://localhost:9090"
      }
    }
  }
}

Go install / build from source

go install github.com/aniketatgithub/prom-mcp@latest

git clone https://github.com/aniketatgithub/prom-mcp && cd prom-mcp
go build -o prom-mcp ./cmd/prom-mcp

Plain binaries for all four platforms are also on the v0.2.0 release, next to the MCPB bundles above.

What to ask

See it in action

Alert triage: why is the node down?

Discover what exists before querying:

Check the trend: is node1 getting worse?

What it looks like

Ask your agent "why is the node down?" and the alert tool answers in triage shape:

1 active alert(s)

[firing] NodeDown (since 2026-10-08T10:00:00Z, value 0)
  labels: {alertname="NodeDown", instance="node1:9100", job="node", severity="critical"}
  summary: Node node1:9100 is down
  description: Scrapes failing for 5m
  rule: up{job="node"} == 0
  group: node.rules
  for: 5m0s

Plus a built-in triage prompt template that walks the agent through alerts, discovery, and trend checks in order.

Tools

Resources: prometheus://alerts (explained alerts), prometheus://config. Prompt: triage.

Try it with no server

prom-mcp demo        # fixture-backed self-test: query, alert explanation, series discovery
prom-mcp query 'up'  # one-shot CLI query against $PROM_URL

Configuration

Config file is JSON, looked up at $PROM_CONFIG, then ./prom-mcp.json, then ~/.prom-mcp.json:

{ "base_url": "https://prometheus.example.com", "token": "…", "timeout_seconds": 30 }

Env vars override the file. No config at all defaults to http://localhost:9090.

Why not just give the agent raw API access?

Agents drown in raw Prometheus JSON and invent metric names that do not exist. prom-mcp returns terse, labelled, triage-shaped text and makes the agent discover before querying. That is the difference between an agent that guesses and an agent that investigates.

Single Go binary, zero dependencies, works fully offline against your own Prometheus.

Comparing servers? See docs/comparison.md for an honest side-by-side with pab1it0/prometheus-mcp-server and the Prometheus org's prometheus/prometheus-mcp.

FAQ

Which AI clients work with prom-mcp? Any MCP client: Claude Code, Cursor, Windsurf, Zed, and custom agents. It speaks newline-delimited JSON-RPC 2.0 over stdio.

How do I connect prom-mcp to a remote Prometheus? Set PROM_URL to your Prometheus base URL (for example http://localhost:9090 or your internal endpoint) when adding the server.

Can an AI agent explain why a Prometheus alert is firing? Yes. prom_alerts_explain joins active alerts with the rule that fired them (expression, summary, description), so the agent can reason about the cause instead of reporting raw JSON.

Does prom-mcp need any API keys or cloud services? No. It is a single local binary talking only to your Prometheus.

How does prom-mcp compare to the other Prometheus MCP servers? See docs/comparison.md. Short version: prom-mcp is the focused alert-triage option with 5 tools; the others cover more of the Prometheus API or ship more deployment machinery.

How is this different from exposing the Prometheus HTTP API to an agent? Raw API access returns nested JSON the agent must parse and invites invented metric names. prom-mcp renders compact labelled text, joins alerts with the rules that fired them, caps long outputs, and nudges discovery before querying. It also retries transient failures and supports bearer-token auth.

Does it work with a remote or auth-protected Prometheus? Yes: set PROM_URL and PROM_TOKEN (or a JSON config file). See Configuration.

Which Prometheus versions are supported? Any server exposing the standard HTTP API (/api/v1/query, query_range, alerts, rules, series, label/<name>/values).

License

MIT. See LICENSE.