prom-evidence-mcp

An evidence-first Prometheus MCP server. It lets an AI agent query production telemetry, but every response carries the receipts: the exact PromQL that ran, when it ran, how many series and samples came back, and explicit warnings when the data is empty, high cardinality, or too thin to support a trend.

Why

I spent years doing production incident response on systems processing over a million orders a day, and the lesson that stuck is that the most dangerous thing in an incident is not missing data, it is a confident conclusion built on partial data. Agents make this worse: they are fluent enough to turn three data points into a convincing root cause story.

This server takes a position: an agent should never be able to read telemetry without also receiving the evidence needed to doubt it. Concretely:

• An empty result comes back with a warning that absence of data is not evidence of absence, and a pointer to verify the metric name first.

• A range query with too few samples per series says plainly that trends computed on it are unreliable.

• A high cardinality result warns that aggregates over hundreds of series are easy to misread.

• target_health exists so the agent can check whether the scrapes behind the numbers are even alive before reasoning about the numbers.

The evidence block is part of the tool contract, so a well-prompted agent cites its queries and coverage the same way a careful engineer pastes the graph link into the incident channel.

Related MCP server: Prometheus MCP Server

Tools

Every response is JSON with result plus an evidence object:

{
  "evidence": {
    "query": "sum(rate(http_requests_total[5m]))",
    "endpoint": "/api/v1/query_range",
    "executed_at": "2026-07-11T22:41:03.512Z",
    "window": { "start": "2026-07-11T20:00:00Z", "end": "2026-07-11T22:00:00Z", "step": "60s" },
    "duration_ms": 84,
    "series_returned": 1,
    "total_samples": 121,
    "warnings": []
  }
}

Install

git clone https://github.com/sharonpammi/prom-evidence-mcp
cd prom-evidence-mcp
npm install
npm run build

Use with Claude Code

claude mcp add prometheus --env PROMETHEUS_URL=https://your-prometheus.example.com -- node /path/to/prom-evidence-mcp/dist/index.js

Use with Claude Desktop

{
  "mcpServers": {
    "prometheus": {
      "command": "node",
      "args": ["/path/to/prom-evidence-mcp/dist/index.js"],
      "env": { "PROMETHEUS_URL": "https://your-prometheus.example.com" }
    }
  }
}

No Prometheus handy? Point it at the public PromLabs demo instance to try it out:

PROMETHEUS_URL=https://demo.promlabs.com npm run smoke

Configuration

Non-goals

This is a read-only window onto telemetry. It deliberately does not expose admin endpoints, remote write, or configuration reload. An agent that can read your metrics should not be one typo away from changing them.

License

MIT