pab1it0/prometheus-mcp-server: a PromQL bridge for MCP clients, installed via Docker or Helm

What problem pab1it0/prometheus-mcp-server solves

An LLM that is asked "why did latency spike at 14:05" has no way to read your metrics. The usual workaround is to paste query output into the chat, or to build a custom function-calling shim around the Prometheus HTTP API. This project removes that work by presenting Prometheus as a set of Model Context Protocol tools, so any MCP-compatible client can call them without project-specific glue code.

The audience is narrow and specific: engineers who already operate Prometheus and who also use an MCP client such as Claude Desktop, Claude Code, VS Code, Cursor or Windsurf. The README states the prerequisites as a reachable Prometheus server plus an MCP-compatible client. If you have neither, the project has nothing to offer you.

The tool surface is deliberately read-only. The README lists execute_query and execute_range_query for PromQL, list_metrics and get_metric_metadata for discovery, get_targets for scrape target inspection, and health_check for container monitoring. There is no tool that writes to Prometheus, which is the correct default for an agent-facing interface but also means the server cannot be used to create recording rules or silence alerts.

How the server talks to Prometheus and to the client

The architecture is a thin adapter. The process holds a PROMETHEUS_URL and issues HTTP requests to the Prometheus API, then wraps the responses as MCP tool results. pyproject.toml pins the runtime dependencies to python-dotenv, requests, starlette, structlog and fastmcp, which confirms the shape: fastmcp builds the MCP surface, requests performs the outbound calls, starlette serves the HTTP transports.

Transport is selectable through PROMETHEUS_MCP_SERVER_TRANSPORT, with stdio as the default and http and sse as alternatives. That choice changes the deployment model, not the query logic. Under stdio the client spawns the process and talks over stdin and stdout, which is why the Claude Desktop example passes the -i flag to docker run. Under http or sse the process binds a socket, with PROMETHEUS_MCP_BIND_HOST defaulting to 127.0.0.1 and PROMETHEUS_MCP_BIND_PORT defaulting to 8080. The Dockerfile overrides the bind host to 0.0.0.0 so the container is reachable from outside, and exposes port 8080.

Two configuration flags are worth reading twice. PROMETHEUS_DISABLE_LINKS, when set to True, strips the Prometheus UI links from query results, and the README says this saves context tokens. That is an honest admission that the default response shape is chatty. PROMETHEUS_REQUEST_TIMEOUT defaults to 30 seconds and the README describes it as protection against hanging requests. Neither flag is required, so a default install inherits both behaviours.

For multi-replica deployments there is PROMETHEUS_MCP_STATELESS_HTTP, defaulting to False, which the README ties to multi-replica support. TOOL_PREFIX renames every tool, so a prefix of staging produces staging_execute_query; the README gives running multiple instances against different environments in Cursor as the reason.

Installing the Prometheus MCP server with Docker or Helm

The fastest path is Docker. The README's manual setup section runs the container with the Prometheus URL supplied as an environment variable, and the -i flag keeps stdin open for the stdio transport.

docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

With basic authentication the same command gains two more variables, PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD. Expect the process to start and then wait quietly for MCP traffic on stdin; it is not an interactive shell, so a silent terminal is normal.

For an MCP client, the README shows a JSON block that registers the server under the key prometheus, with the command set to docker and the URL passed through env. The Claude Code variant is a single CLI call:

claude mcp add prometheus --env PROMETHEUS_URL=http://your-prometheus:9090 -- docker run -i --rm -e PROMETHEUS_URL ghcr.io/pab1it0/prometheus-mcp-server:latest

On Kubernetes the project publishes an OCI Helm chart. The README's example pins chart version 1.1.1, which is older than the v1.6.2 release of the server itself, so check the chart's own version line rather than assuming the two move together.

helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  --set prometheus.url="http://prometheus:9090"

A first real use is a range query over a known metric. Ask the client to call execute_range_query with a metric you can verify by hand, and compare the returned series against the same query in the Prometheus UI. If the numbers match, the wiring is correct; if the call times out, PROMETHEUS_REQUEST_TIMEOUT is the first knob to raise.

Authentication coverage and where it stops

The environment variables cover basic auth, a bearer token, mutual TLS via PROMETHEUS_CLIENT_CERT and PROMETHEUS_CLIENT_KEY, a CA bundle through REQUESTS_CA_BUNDLE, and an ORG_ID for multi-tenant setups. PROMETHEUS_URL_SSL_VERIFY can be set to False to disable certificate verification, and PROMETHEUS_CUSTOM_HEADERS accepts a JSON string for anything the named variables do not express.

That is a wider net than most single-purpose MCP servers cast, and the custom headers escape hatch is the reason the list does not need to be exhaustive. The trade-off is that every credential arrives as a plain environment variable. The README does not document a secrets-manager integration, a file-based credential source, or any redaction of credentials from logs, even though structlog is a dependency. If your Prometheus sits behind an identity-aware proxy that requires a browser redirect or a short-lived token refreshed out of band, none of these variables will carry you, and PROMETHEUS_CUSTOM_HEADERS only helps if you can produce the header value yourself.

Setting PROMETHEUS_URL_SSL_VERIFY to False removes the check between this process and Prometheus. The README presents it as an option without qualification, which is a choice worth noticing rather than copying.

The read-only boundary and other limits

The tool list in the README contains no write operations, so the server cannot create alerts, write series, or change configuration. For an agent-facing component that is the right boundary, but it rules the project out for anyone hoping to automate Prometheus administration through a chat client.

A second limit is the query surface itself. execute_query and execute_range_query take PromQL, which means the model must produce valid PromQL. Nothing in the documented tool set validates a query before it reaches Prometheus, and an expensive range query over a long window against a large Prometheus is exactly the kind of request an eager assistant will generate. PROMETHEUS_REQUEST_TIMEOUT caps how long the server waits, not how much work Prometheus does.

Third, the README documents the transport modes and the stateless HTTP flag but does not describe session handling, concurrency limits, or what happens to in-flight requests when the container restarts. The Dockerfile health check probes /health over HTTP for the http and sse transports and falls back to pgrep for stdio, which tells you the container reports health but not how it behaves under load.

Finally, the README's own framing of PROMETHEUS_DISABLE_LINKS as a token-saving option implies that default responses carry more text than a model needs. On a long conversation with many queries, that overhead accumulates.

How it differs from the AWS Labs Prometheus MCP server

The AWS Labs Prometheus MCP server is the comparison that comes up most often, and the difference is deployment target rather than protocol. AWS Labs builds for Amazon Managed Service for Prometheus, so its authentication path runs through AWS credentials and SigV4 signing. This project targets a Prometheus HTTP endpoint that you reach directly, and its authentication options are the ones listed above: basic auth, bearer token, mutual TLS, a CA bundle, custom headers.

If your metrics live in Amazon Managed Service for Prometheus, the AWS Labs server matches the environment and this one does not, because none of its documented variables produce a SigV4 signature. If your Prometheus is self-hosted, in-cluster, or behind a reverse proxy with basic auth, this project's configuration maps onto that directly and the AWS credential chain is irrelevant.

The second difference is packaging. This project ships a container image on ghcr.io, an OCI Helm chart, and a Docker Desktop catalog entry. The README does not document a PyPI install path even though pyproject.toml defines a console script named prometheus-mcp-server, so the supported route is the container or the chart.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-08-05. Release v1.6.2 landed on 2026-08-03, preceded by v1.6.1 on 2026-05-01 and v1.6.0 on 2026-03-07. That is a steady cadence across the year, with the most recent release close to the most recent push.

The licence is MIT, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is permissive and carries no copyleft obligation for the server itself. It says nothing about the licence of the Prometheus instance you point it at, and nothing about the MCP client you connect it to.

Upgrade cost is low but not zero. The server is a stateless adapter, so a container tag change is the whole upgrade. The moving parts are the chart version and the image tag, which the README shows as separate numbers: chart 1.1.1 in the Helm example against server release v1.6.2. Pin both. The Python floor is 3.10, and the Dockerfile builds on python:3.12-slim-bookworm, so anyone installing from source needs 3.10 or newer. Coverage is configured with fail_under = 80 in pyproject.toml, which means a test run below that threshold fails rather than warns.

Editorial conclusion

Adopt it if you already run Prometheus and want an MCP client such as Claude Desktop, Cursor or VS Code to read metrics without a bespoke integration layer; the Docker image and the Helm chart keep the deployment small. Skip it if you need to write to Prometheus, if your Prometheus sits behind an auth scheme the environment variables cannot express, or if you want a long-lived HTTP service with a documented session model. Before rolling it out, verify that your Prometheus URL answers from inside the container network and decide whether PROMETHEUS_DISABLE_LINKS should be set, because the links the server returns are the part that spends context tokens.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. pab1it0/prometheus-mcp-server on GitHub
4. README
5. Releases