prometheus-mcp-server: giving an LLM read access to PromQL
A Model Context Protocol (MCP) server that enables AI agents and LLMs to query and analyze Prometheus metrics through standardized interfaces.
At a glance
- What is it?
- This MCP server wraps a Prometheus HTTP API in a small set of tools so an assistant can run instant and range queries and browse metric metadata. It is a thin, stateless bridge, and its limits follow from that thinness.
- Who is it for?
- Adopt it if you already run Prometheus and want an MCP client to answer questions against it without building a custom tool layer; the Docker image, Helm chart and stdio transport cover the common cases. Skip it if you need write access, recording rules, Alertmanager state, or anything beyond what the Prometheus HTTP API already exposes, and do not point it at a Prometheus instance whose data would be sensitive if a model quoted it back.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 41 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap between a metrics store and a chat client
Prometheus answers HTTP requests. MCP clients speak a different protocol, and most of them cannot construct a URL, pick a step interval, or parse the JSON envelope that a PromQL response returns. The gap is normally filled by a human who knows the metric names. prometheus-mcp-server fills it with a process: it runs as an MCP server, receives tool calls from the client, translates them into Prometheus HTTP API requests, and returns the results. The README describes the intent plainly: it gives AI assistants the ability to "execute PromQL queries and analyze your metrics data" through standardized MCP interfaces. The audience is therefore narrow and specific. It is for engineers who already operate Prometheus and who already use an MCP-capable client, and who want the model to reach the metrics without writing a bespoke integration. If you do not run Prometheus, or your client does not speak MCP, there is nothing here for you.
What the server actually exposes as tools
The tool surface is small and read-only. execute_query runs a PromQL instant query. execute_range_query runs the same query across a start time, end time and step interval. list_metrics enumerates available metric names with pagination and filtering. get_metric_metadata returns metadata for one metric or in bulk, with optional filtering. get_targets returns scrape targets. health_check exists for container monitoring and status verification. That list is the whole contract, and it maps almost one to one onto Prometheus HTTP API endpoints. There is no tool for writing series, no tool for creating or editing recording rules, no tool for querying Alertmanager, and nothing that touches the Prometheus configuration. The server is a translator, not a control plane. Anyone expecting an agent that can silence an alert or adjust a scrape interval will not find it here.
How a query travels from the client to Prometheus
The data flow is short enough to describe in one pass. The MCP client launches the server as a subprocess (the Claude Desktop example uses docker run -i --rm) or connects to it over HTTP or SSE. The model decides to call a tool such as execute_query, the client forwards that call, and the server issues an HTTP request to the URL in PROMETHEUS_URL. Credentials come from PROMETHEUS_USERNAME and PROMETHEUS_PASSWORD for basic auth, PROMETHEUS_TOKEN for a bearer token, or PROMETHEUS_CLIENT_CERT and PROMETHEUS_CLIENT_KEY for mutual TLS, with REQUESTS_CA_BUNDLE for verifying the server certificate. The response is shaped into the MCP result and returned to the model. Two configuration keys change that payload rather than the request. PROMETHEUS_DISABLE_LINKS, when set to True, strips Prometheus UI links from query results, which the README says saves context tokens. PROMETHEUS_REQUEST_TIMEOUT defaults to 30 seconds and is described as protection against hanging requests. Both are sensible defaults, and the token-saving one is the more interesting design decision: it acknowledges that the model's context window, not the network, is the scarce resource.
Running it: the four paths the README documents
There are four installation routes. For Claude Desktop, add an entry to the MCP configuration with command docker and args run -i --rm -e PROMETHEUS_URL ghcr.io/pab1it0/prometheus-mcp-server:latest, and set PROMETHEUS_URL in the env block. For Claude Code, the README gives a single CLI line: 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. For VS Code, Cursor and Windsurf, the JSON block is the same shape as the Claude Desktop one. For Kubernetes, the project publishes an OCI Helm chart, installed as helm install prometheus-mcp-server oci://ghcr.io/pab1it0/charts/prometheus-mcp-server --version 1.1.1 --set prometheus.url="http://prometheus:9090". Note the version: the chart is at 1.1.1 while the application releases are at 1.6.x, so the two version lines move independently and you should not read the chart version as the server version. Authentication in the chart goes through --set auth.username and --set auth.password. Docker Desktop users get a catalog and MCP Toolkit path, which is the lowest-friction option but also the least transparent about what is being configured.
Transport, multi-tenancy and the keys that matter at scale
The default transport is stdio, which means the client owns the process lifetime and there is no network listener to secure. Setting PROMETHEUS_MCP_SERVER_TRANSPORT to http or sse changes that, and then PROMETHEUS_MCP_BIND_HOST (default 127.0.0.1) and PROMETHEUS_MCP_BIND_PORT (default 8080) decide where it listens. The loopback default is the right choice, but it also means a containerised deployment needs an explicit change before anything outside the pod can reach it. PROMETHEUS_MCP_STATELESS_HTTP exists for multi-replica support, which tells you the HTTP mode otherwise carries session state and will not load-balance cleanly across replicas. For multi-tenant Prometheus setups there is ORG_ID, and for anything not covered by the built-in auth options there is PROMETHEUS_CUSTOM_HEADERS, a JSON string. TOOL_PREFIX is the key I would flag to anyone running more than one environment: setting it to staging renames the tools to staging_execute_query and so on, which the README says is useful for running multiple instances against different environments in Cursor. Without it, two servers in one client present identically named tools and the model has no way to tell production from staging.
Where this design stops being the right tool
The limitations follow directly from the read-only, endpoint-mirroring design. First, the server can only answer what PromQL can answer. If your question requires correlating metrics with logs, traces, or deployment events, execute_query will not help, and the model will either say so or, worse, produce a plausible-looking query that returns an empty result. Empty results are the failure mode to watch for, because a model that receives no data may explain the absence rather than the query. Second, PROMETHEUS_URL_SSL_VERIFY can be set to False to disable certificate verification. That is a convenience flag, and it should stay unset unless you are debugging against a self-signed endpoint, because it silently removes the guarantee that you are talking to the Prometheus you think you are. Third, the 30 second timeout is a ceiling on slow queries, not a fix for them; a range query over a long window with a small step will still be expensive on the Prometheus side, and the server does not appear to cap the range or step the client requests. Fourth, and most important for adoption decisions: the server exposes whatever the Prometheus instance exposes. There is no per-metric or per-label filtering described in the README, so if your Prometheus holds data that should not flow into a third-party model's context, this bridge does not draw that boundary for you. That is an architectural property, not a bug, but it decides a lot of deployments.
How it compares to wiring PromQL into an agent yourself
The obvious alternative is not another MCP server; it is the thing most teams already have, which is a small internal tool or function-calling wrapper around the Prometheus HTTP API. The difference is where the work sits. A hand-written wrapper gives you control over which endpoints are exposed, what the response shape looks like, whether results are truncated, and which metrics a given user is allowed to see. prometheus-mcp-server gives you none of that per-deployment shaping, but it gives you the MCP handshake, the tool schemas, the stdio and HTTP transports, the container image and the Helm chart, and it gives them to you in a form that Claude Desktop, Claude Code, VS Code, Cursor and Windsurf already understand. The trade is configuration surface for integration surface. If your requirement is "let the model see CPU and memory for the services it is debugging", the wrapper is more code but tighter. If your requirement is "let the model query the metrics we already have, in the client we already use, this week", this project is the shorter path, and the environment variable table is the entire learning curve. The other honest comparison is to Grafana's own MCP work and to the various Prometheus-compatible query frontends; I cannot assess those from this material, and the README does not position the project against them, so treat any comparison you read elsewhere as unverified.
Maintenance, licensing and what to check before you commit
The project is MIT licensed, which permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of the licence implication I can state from the material; anything about your organisation's policy on model providers reading production telemetry is a separate question and not a licensing one. On maintenance, the release cadence visible in the supplied data is three releases between March and August 2026, with v1.6.2 on 2026-08-03 and a push to main on 2026-08-05, so the repository is active rather than dormant. The Helm chart version (1.1.1 in the README example) trails the application version, which means upgrades have two coordinates and you should pin both. Python 3.10 or later is required if you run it outside the container. The container image is published to GitHub Container Registry, so an air-gapped cluster needs a mirror before the Helm install will succeed. Before adopting, verify that the tool list matches your actual question set, that PROMETHEUS_DISABLE_LINKS is set if context budget matters to you, and that you have decided what data the model is allowed to see, because the server will hand over whatever the Prometheus URL returns.
Editorial conclusion
Adopt it if you already run Prometheus and want an MCP client to answer questions against it without building a custom tool layer; the Docker image, Helm chart and stdio transport cover the common cases. Skip it if you need write access, recording rules, Alertmanager state, or anything beyond what the Prometheus HTTP API already exposes, and do not point it at a Prometheus instance whose data would be sensitive if a model quoted it back. Before rolling it out, verify three things: that PROMETHEUS_URL is reachable from inside the container, that PROMETHEUS_DISABLE_LINKS is set to True if you care about context budget, and that TOOL_PREFIX is set if you plan to run more than one instance against different environments in the same client.
Community notes