Allows LLMs to interact with Prometheus instances to execute PromQL queries, analyze metrics, and manage monitoring configurations.
Also known as prometheus/prometheus-mcp, prometheus-mcp
- Stars
- 142
- Tools
- 30
- Downloads, 30 days
- —
- Latest version
- 0.19.0-rc.0
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is Prometheus MCP?
Prometheus allows LLMs to interact with Prometheus instances to execute PromQL queries, analyze metrics, and manage monitoring configurations. It exposes 30 tools, such as alertmanagers, build_info, clean_tombstones.
Summary generated from the project's README
About Prometheus MCP server
Monitoring infrastructure and troubleshooting metrics through an AI interface is what the Prometheus MCP Server enables. It allows large language models to connect to running Prometheus instances via their API to execute PromQL queries, analyze metric metadata, and manage monitoring configurations. This server is designed for DevOps engineers and SREs who want to use natural language to investigate system health or optimize their monitoring setup.
Users can interact with the server locally by configuring it with specific command-line flags. To manage token usage and context efficiency, the server offers TOON encoding for structured data and API response truncation to limit the amount of information sent to the model. While most tools are available by default, users can whitelist specific tools or enable potentially destructive TSDB Admin API endpoints using the --dangerous.enable-tsdb-admin-tools flag. The server also includes embedded runbooks that act as guided workflows for common tasks like high-cardinality optimization or error-rate investigation.
What you can do with it
- 1Investigate slow metric queriesAsk the AI to identify why querying specific metrics is performing poorly.
- 2Generate SLO recording rulesUse the server to analyze existing metrics and suggest new recording rules for service level objectives.
- 3Perform system health reviewsRequest a comprehensive summary of a Prometheus instance including its configuration and runtime information.
- 4Optimize high cardinality dataUtilize built-in runbooks to find and resolve issues related to high cardinality in your metrics.
Written from the project's README. Every use case is checked against a quote from it.
How to install Prometheus MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Prometheus MCP in Claude Code
$ claude mcp add prometheus-mcp -- docker run -i --rm docker.io/prom/prometheus-mcp:v0.19.0-rc.0Install Prometheus MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"prometheus-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/prom/prometheus-mcp:v0.19.0-rc.0"
]
}
}
}Install Prometheus MCP in VS Code
.vscode/mcp.json
{
"servers": {
"prometheus-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/prom/prometheus-mcp:v0.19.0-rc.0"
]
}
}
}Install Prometheus MCP in VS Code CLI
$ code --add-mcp '{"name":"prometheus-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","docker.io/prom/prometheus-mcp:v0.19.0-rc.0"]}'Install Prometheus MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"prometheus-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/prom/prometheus-mcp:v0.19.0-rc.0"
]
}
}
}Install Prometheus MCP in Codex
$ codex mcp add prometheus-mcp -- docker run -i --rm docker.io/prom/prometheus-mcp:v0.19.0-rc.0Install Prometheus MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.prometheus-mcp] command = "docker" args = ["run", "-i", "--rm", "docker.io/prom/prometheus-mcp:v0.19.0-rc.0"]
Install Prometheus MCP in Gemini CLI
$ gemini mcp add -s user prometheus-mcp docker -- run -i --rm docker.io/prom/prometheus-mcp:v0.19.0-rc.0Install Prometheus MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"prometheus-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"docker.io/prom/prometheus-mcp:v0.19.0-rc.0"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for docker.io/prom/prometheus-mcp:v0.19.0-rc.0 v0.19.0-rc.0 in an isolated container with no network and no keys. It answered and listed 30 tools.
Prometheus MCP tools 30
Read from the server with tools/listalertmanagersRead-onlyGet overview of Prometheus Alertmanager discovery
build_infoRead-onlyGet Prometheus build information
clean_tombstonesActionRemoves the deleted data from disk and cleans up the existing tombstones. I/O- and CPU-intensive; prefer low-traffic periods and confirm with the user before calling.
configRead-onlyGet Prometheus configuration
delete_seriesActionDeletes data for a selection of series in a time range. Both start_time and end_time are required to prevent accidental deletion of all data. Deletion creates tombstones; run clean_tombstones or wait for compaction to reclaim disk space. Confirm the time range and matchers with the user before calling.
docs_listRead-onlyList of Official Prometheus Documentation Files.
docs_readRead-onlyRead the named markdown file containing official Prometheus documentation from the prometheus/docs repo
docs_searchRead-onlySearch the markdown files containing official Prometheus documentation from the prometheus/docs repo
exemplar_queryRead-onlyExecute an exemplar query against the Prometheus datasource to find trace exemplars associated with metric samples
flagsRead-onlyGet runtime flags
healthyRead-onlyManagement API endpoint that can be used to check Prometheus health.
label_namesRead-onlyReturns the unique label names present in the block in sorted order by given time range and matches
| alertmanagers | Get overview of Prometheus Alertmanager discovery | Read-only |
| build_info | Get Prometheus build information | Read-only |
| clean_tombstones | Removes the deleted data from disk and cleans up the existing tombstones. I/O- and CPU-intensive; prefer low-traffic periods and confirm with the user before calling. | Action |
| config | Get Prometheus configuration | Read-only |
| delete_series | Deletes data for a selection of series in a time range. Both start_time and end_time are required to prevent accidental deletion of all data. Deletion creates tombstones; run clean_tombstones or wait for compaction to reclaim disk space. Confirm the time range and matchers with the user before calling. | Action |
| docs_list | List of Official Prometheus Documentation Files. | Read-only |
| docs_read | Read the named markdown file containing official Prometheus documentation from the prometheus/docs repo | Read-only |
| docs_search | Search the markdown files containing official Prometheus documentation from the prometheus/docs repo | Read-only |
| exemplar_query | Execute an exemplar query against the Prometheus datasource to find trace exemplars associated with metric samples | Read-only |
| flags | Get runtime flags | Read-only |
| healthy | Management API endpoint that can be used to check Prometheus health. | Read-only |
| label_names | Returns the unique label names present in the block in sorted order by given time range and matches | Read-only |
Show all 30 toolsShow fewer tools
label_valuesRead-onlyPerforms a query for the values of the given label, time range and matches
list_alertsRead-onlyList all active alerts
list_rulesRead-onlyList all alerting and recording rules that are loaded
list_targetsRead-onlyGet overview of Prometheus target discovery
metric_metadataRead-onlyReturns metadata about metrics currently scraped by the metric name.
queryRead-onlyExecute an instant query against the Prometheus datasource, returning one value per series at a single point in time
quitActionManagement API endpoint that can be used to trigger a graceful shutdown of Prometheus. Only call this when the user explicitly requests a shutdown.
range_queryRead-onlyExecute a range query against the Prometheus datasource, returning values over a time window; use for graphing and trend analysis
readyRead-onlyManagement API endpoint that can be used to check Prometheus is ready to serve traffic (i.e. respond to queries.)
reloadActionManagement API endpoint that can be used to trigger a reload of the Prometheus configuration and rule files. Safe; applies changes without downtime.
runbooks_listRead-onlyList the runbooks embedded in this server: guided workflows (Agent Skills) for common Prometheus tasks - investigating error rates and alert spikes, finding top CPU/memory/disk consumers, troubleshooting missing metrics or empty query results, health-checking Prometheus, reducing high-cardinality metrics, reviewing and drafting recording and alerting rules, and tuning Prometheus configuration. Call this and read the matching runbook with runbooks_read before starting any of these tasks.
runbooks_readRead-onlyRead the named runbook: a guided workflow (Agent Skill) for a common Prometheus task, expressed in terms of this server's tools. Follow its guidance when a user request matches a runbook's purpose; runbooks_list shows what is available.
runtime_infoRead-onlyGet Prometheus runtime information
seriesRead-onlyFinds series by label matches
snapshotActioncreates a snapshot of all current data into snapshots/<datetime>-<rand> under the TSDB's data directory and returns the directory as response. Safe, but confirm with the user before calling.
targets_metadataRead-onlyReturns metadata about metrics currently scraped by the target
tsdb_statsRead-onlyGet usage and cardinality statistics from the TSDB
wal_replay_statusRead-onlyGet current WAL replay status
| label_values | Performs a query for the values of the given label, time range and matches | Read-only |
| list_alerts | List all active alerts | Read-only |
| list_rules | List all alerting and recording rules that are loaded | Read-only |
| list_targets | Get overview of Prometheus target discovery | Read-only |
| metric_metadata | Returns metadata about metrics currently scraped by the metric name. | Read-only |
| query | Execute an instant query against the Prometheus datasource, returning one value per series at a single point in time | Read-only |
| quit | Management API endpoint that can be used to trigger a graceful shutdown of Prometheus. Only call this when the user explicitly requests a shutdown. | Action |
| range_query | Execute a range query against the Prometheus datasource, returning values over a time window; use for graphing and trend analysis | Read-only |
| ready | Management API endpoint that can be used to check Prometheus is ready to serve traffic (i.e. respond to queries.) | Read-only |
| reload | Management API endpoint that can be used to trigger a reload of the Prometheus configuration and rule files. Safe; applies changes without downtime. | Action |
| runbooks_list | List the runbooks embedded in this server: guided workflows (Agent Skills) for common Prometheus tasks - investigating error rates and alert spikes, finding top CPU/memory/disk consumers, troubleshooting missing metrics or empty query results, health-checking Prometheus, reducing high-cardinality metrics, reviewing and drafting recording and alerting rules, and tuning Prometheus configuration. Call this and read the matching runbook with runbooks_read before starting any of these tasks. | Read-only |
| runbooks_read | Read the named runbook: a guided workflow (Agent Skill) for a common Prometheus task, expressed in terms of this server's tools. Follow its guidance when a user request matches a runbook's purpose; runbooks_list shows what is available. | Read-only |
| runtime_info | Get Prometheus runtime information | Read-only |
| series | Finds series by label matches | Read-only |
| snapshot | creates a snapshot of all current data into snapshots/<datetime>-<rand> under the TSDB's data directory and returns the directory as response. Safe, but confirm with the user before calling. | Action |
| targets_metadata | Returns metadata about metrics currently scraped by the target | Read-only |
| tsdb_stats | Get usage and cardinality statistics from the TSDB | Read-only |
| wal_replay_status | Get current WAL replay status | Read-only |
Configuration
PROMETHEUS_MCP_PROMETHEUS_URL
| Name | Description | |
|---|---|---|
| PROMETHEUS_MCP_PROMETHEUS_URL | — |
Automated checks
Ran Nov 16, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableprometheus/prometheus-mcp is public and reachablegithub.com/prometheus/prometheus-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-14github.com/prometheus/prometheus-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model30 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledDestructive tools carry destructiveHintPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubPrometheus MCP Server

About
This is an MCP server to allow LLMs to interact with a running Prometheus instance via the API to do things like generate and execute promql queries, list and analyze metrics, etc.
Demos and Examples
Asking Claude to Investigate Slow Queries
The prompt used was:
querying my metrics is slow, can you help me figure out why?
Investigate metrics produced by the MCP server itself and suggest recording rules for SLOs
The prompt used was:
use the tools from the prometheus mcp server to investigate the metrics from the mcp server and suggest prometheus recording rules for SLOs
Summarize Prometheus metric/label naming best practices
The prompt used was:
summarize prometheus metric/label name best practices
Report on the health of the Prometheus instance that powers prometheus.demo.prometheus.io
The prompt used was:
please provide a comprehensive review and summary of the prometheus server. review it's configuration, flags, runtime/build info, and anything else that you feel may provide insight into the status of the prometheus instance, including analyzing metrics and executing queries
Tools
The Prometheus HTTP API outputs JSON data, and the tools in this MCP server return that JSON to the LLM for processing as it's structured and well understood by LLMs.
LLMs and Token/Context Efficiency
This MCP server supports the following options which have the potential to reduce token/context usage:
TOON Encoding
If token/context usage is a concern, this MCP server also supports converting the API's JSON data to the Token-Oriented Object Notation (TOON) format. While it is not guaranteed to reduce token usage, it is designed with token efficiency in mind. As noted on TOON's documentation, it excels at uniform arrays of objects; non-uniform/complex objects may still be more token-efficient in JSON. Real world token usage will depend on usage patterns, please review common workflows to determine if TOON output may be beneficial. Please see Flags for more information on the available flags and their corresponding environment variables.
API Response Truncation
This feature allows you to set a maximum limit on the number of lines or entries returned from the Prometheus API for, which can help in reducing the amount of data sent to the LLM.
Setting the limit to 0 disables truncation.
Truncation is disabled by default.
Note that LLMs capable of handling tool request arguments can override this global truncation limit on a per-tool-call basis for supported tools.
Please see Flags for more information on the available flags and their corresponding environment variables.
Full Tool List
| Tool Name | Description |
|---|---|
alertmanagers |
Get overview of Prometheus Alertmanager discovery |
build_info |
Get Prometheus build information |
config |
Get Prometheus configuration |
docs_list |
List of Official Prometheus Documentation Files |
docs_read |
Read the named markdown file containing official Prometheus documentation from the prometheus/docs repo |
docs_search |
Search the markdown files containing official Prometheus documentation from the prometheus/docs repo |
exemplar_query |
Performs a query for exemplars by the given query and time range |
flags |
Get runtime flags |
healthy |
Management API endpoint that can be used to check Prometheus health |
label_names |
Returns the unique label names present in the block in sorted order by given time range and matchers |
label_values |
Performs a query for the values of the given label, time range and matchers |
list_alerts |
List all active alerts |
list_rules |
List all alerting and recording rules that are loaded |
list_targets |
Get overview of Prometheus target discovery |
metric_metadata |
Returns metadata about metrics currently scraped by the metric name |
query |
Execute an instant query against the Prometheus datasource, returning one value per series at a single point in time |
quit |
Management API endpoint that can be used to trigger a graceful shutdown of Prometheus |
range_query |
Execute a range query against the Prometheus datasource, returning values over a time window |
ready |
Management API endpoint that can be used to check Prometheus is ready to serve traffic (i.e. respond to queries |
reload |
Management API endpoint that can be used to trigger a reload of the Prometheus configuration and rule files |
runbooks_list |
List the runbooks embedded in this server: guided workflows (Agent Skills) for common Prometheus tasks |
runbooks_read |
Read the named runbook by skill name (e.g. check-system-health) |
runtime_info |
Get Prometheus runtime information |
series |
Finds series by label matchers |
targets_metadata |
Returns metadata about metrics currently scraped by the target |
tsdb_stats |
Get usage and cardinality statistics from the TSDB |
wal_replay_status |
Get current WAL replay status |
NOTE:
Because the TSDB Admin API endpoints allow for potentially destructive operations like deleting data, they are not enabled by default. In order to enable the TSDB Admin API endpoints, the MCP server must be started with the flag
--dangerous.enable-tsdb-admin-toolsto acknowledge the associated risk these endpoints carry.
| Tool Name | Description |
|---|---|
clean_tombstones |
Removes the deleted data from disk and cleans up the existing tombstones |
delete_series |
deletes data for a selection of series in a time range |
snapshot |
creates a snapshot of all current data into snapshots/- under the TSDB's data directory and returns the directory as response |
Tool Sets
The server exposes many tools to interact with Prometheus. There are tools to interact with Prometheus via the API, as well as additional tools to do things like read documentation, etc. By default, they are all registered and available for use (TSDB Admin API tools need an extra flag).
To be considerate to LLMs with smaller context windows, it's possible to pass in a whitelist of specific tools to register with the server.
The following 'core' tools are always loaded: [docs_list, docs_read, docs_search, runbooks_list, runbooks_read, query, range_query, metric_metadata, label_names, label_values, series].
Additional tools can be specified with the --mcp.tools flag.
For example, the command line:
prometheus-mcp --mcp.tools=build_info --mcp.tools=flags --mcp.tools=runtime_info
Would result in the following tools being loaded:
build_infodocs_listdocs_readdocs_searchflagslabel_nameslabel_valuesmetric_metadataqueryrange_queryrunbooks_listrunbooks_readruntime_infoseries
Runbooks (Agent Skills) and Prompts
The server embeds a set of runbooks: guided workflows for common Prometheus tasks, expressed in terms of the server's tools. Each runbook orients the model on the relevant tools, then suggests topics to explore with example queries rather than prescribing a fixed sequence of steps. Runbooks cover tasks like system health checks, missing-data triage, error-rate investigation, high-cardinality optimization, recording/alerting rule review, and configuration/performance tuning.
Each runbook is packaged as a full Agent Skill: a directory containing a SKILL.md with name/description frontmatter.
Runbooks are exposed three ways:
- Tools: the model can discover and read them itself via the
runbooks_list/runbooks_readtools when a request matches a runbook's purpose. Tools are the most portable path and work in every MCP client. - Skill resources: per the SEP-2640 skills extension draft, each runbook is a
skill://<name>/SKILL.mdresource, enumerated by the well-knownskill://index.jsondiscovery index, and the server declares theio.modelcontextprotocol/skillsextension capability. Skill-aware hosts can consume these like local filesystem skills; other clients can still read them as ordinary MCP resources. - MCP prompts: each runbook is also registered as an MCP prompt under its skill name (e.g.
check-system-health,optimize-high-cardinality), so clients with prompt support can invoke a guided workflow directly (often surfaced as slash commands).
Prometheus Compatible Backends
There are many Prometheus compatible backends that can be used to extend prometheus in a variety of ways, often with the goals of offering long term storage or query aggregation from multiple prometheus instances. Some examples can be found in the Remote Storage of prometheus' docs.
Many of those services also offer a "prometheus compatible" API that can be used to query/interact with the data using native promQL. In general, this MCP server should at a minimum work for other prometheus API compatible services to execute queries and interact with the series/labels/metadata endpoints for metric and label discovery. Beyond that, there may be API differences as the different systems implement different parts/extensions of the API for their needs.
Examples:
- Thanos does not use a centralized config, so the config endpoint is not implemented and thus the config tool is removed.
- Mimir and Cortex implement extra endpoints to manage/add/remove rules
To workaround this and provide a better experience on some of the commonly used Prometheus compatible systems, this project may add direct support for select systems to provide different/more tools.
Choosing a specific prometheus backend implementation can be done with the --prometheus.backend flag.
The list of available backend implementations on a given release of the MCP server can be found in the output of the --help flag.
Qualifications and support criteria are still under consideration, please open an issue to request support/features for a specific backend for further discussion.
Prometheus Backend Implementation Differences
| Backend | Tool | Add/Remove/Change | Notes |
|---|---|---|---|
prometheus |
n/a | none | Standard prometheus tools. Functionally equivalent to --mcp.tools="all". The default MCP server toolset. |
thanos |
alertmanagers |
remove | Thanos does not implement the endpoint and the tool returns a 404. |
thanos |
clean_tombstones |
remove | Prometheus TSDB admin endpoint |
thanos |
config |
remove | Thanos does not use a centralized config, so it doesn't implement the endpoint and the tool returns a 404. |
thanos |
delete_series |
remove | Prometheus TSDB admin endpoint |
thanos |
list_stores |
add | Thanos provides an additional endpoint to list store API servers. |
thanos |
quit |
remove | Thanos does not implement the endpoint and the tool returns a 404. |
thanos |
reload |
remove | Thanos does not implement the endpoint and the tool returns a 404. |
thanos |
snapshot |
remove | Prometheus TSDB admin endpoint |
thanos |
targets_metadata |
remove | Thanos does not implement the endpoint and the tool returns a 404 (thanos-io/thanos#7119). |
thanos |
wal_replay_status |
remove | Thanos does not implement the endpoint and the tool returns a 404. |
Resources
| Resource Name | Resource URI | Description |
|---|---|---|
| List of Official Prometheus Documentation Files | prometheus://docs |
List of official Prometheus Documentation files |
| Read Official Prometheus Documentation | prometheus://docs/{+file} |
Read official Prometheus Documentation files by name |
| Agent Skills Discovery Index | skill://index.json |
SEP-2640 discovery index of the embedded runbooks/skills |
| Prometheus Runbook (Agent Skill) | skill://<name>/SKILL.md |
Read the named runbook, packaged as an Agent Skill (one resource per runbook) |
Installation and Usage
This MCP server is most useful when fully integrated with tooling and/or installed as a tool server with another system. Installation procedures and integration support will vary depending on the tools being used. For example:
- some systems can only interact with MCP tools and not resources/prompts
- some systems use mcp.json config file format to manage MCP servers and some require custom formats
- some systems don't speak MCP directly and require tools like mcp-to-openapi to proxy
Please check the documentation for the tool being used/integrated for specific instructions and level of support.
Transports
The server speaks MCP over stdio (the default) or HTTP (--mcp.transport=http, served at /mcp on the web listen address).
MCP protocol revisions 2024-11-05 through 2026-07-28 are supported, and the client chooses which one to use.
Over HTTP, only the Streamable HTTP transport is served; the older HTTP+SSE transport is not.
With stdio, the web listener is enabled by default. Set --no-web.listen (or PROMETHEUS_MCP_WEB_LISTEN=false) to disable it.
This makes metrics, health and readiness endpoints, pprof, the landing page, and HTTP documentation unavailable; MCP documentation tools remain available.
The HTTP transport is stateless: each request is handled on its own and no session is tracked, so replicas can sit behind any load balancer without session affinity. What follows from that:
- Only
POSTis served. The standaloneGETstream some clients open answers405 Method Not Allowed, which is harmless: everything the server sends rides the response to a request. - Keepalive pings (
--mcp.keepalive-interval) are only sent onstdio; there is no session to ping over HTTP. - A client that disconnects mid-call cancels the in-flight Prometheus query on current MCP revisions; older clients' calls run to completion.
--mcp.session-timeoutis deprecated and ignored.
--mcp.enable-client-logging forwards the log lines tool handlers emit to the client as MCP log notifications, in addition to the normal log output.
MCP has deprecated this feature. It keeps working during the deprecation window, but what a client receives is up to the client: newer clients must ask for a log level, and older clients over HTTP get info and above.
Binary
Download a release appropriate for your system from the Releases page. The commands below are for v0.19.0 and later; see the upgrade note below for earlier releases. Please see Flags for more information on the available flags and their corresponding environment variables.
/path/to/prometheus-mcp <flags>
# or using env vars
PROMETHEUS_MCP_PROMETHEUS_URL="https://$yourPrometheus:9090" /path/to/prometheus-mcp
Upgrading from v0.18.0 or earlier: as of v0.19.0 the binary is named prometheus-mcp (previously prometheus-mcp-server), and its environment variables use the PROMETHEUS_MCP_ prefix instead of PROMETHEUS_MCP_SERVER_.
The old variable names are ignored without an error, so rename them when you upgrade.
Docker
Please see Flags for more information on the available flags and their corresponding environment variables.
# Stdio transport
docker run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url "https://$yourPrometheus:9090"
# or using env vars
docker run --rm -i -e PROMETHEUS_MCP_SERVER_PROMETHEUS_URL="https://$yourPrometheus:9090" ghcr.io/tjhop/prometheus-mcp-server:latest
# HTTP transport
docker run --rm -p 8080:8080 ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url "https://$yourPrometheus:9090" --mcp.transport "http" --web.listen-address ":8080"
# or using env vars
docker run --rm -p 8080:8080 -e PROMETHEUS_MCP_SERVER_PROMETHEUS_URL="https://$yourPrometheus:9090" -e PROMETHEUS_MCP_SERVER_MCP_TRANSPORT="http" -e PROMETHEUS_MCP_SERVER_WEB_LISTEN_ADDRESS=":8080" ghcr.io/tjhop/prometheus-mcp-server:latest
Helm Chart (Kubernetes)
A Helm chart is available for deploying to Kubernetes. The chart is published as an OCI artifact on each release.
helm install prometheus-mcp-server oci://ghcr.io/tjhop/charts/prometheus-mcp-server \
--version <version> \
--set prometheus.url=http://prometheus:9090
See the chart README for the full list of configuration values and examples.
Kubernetes (Raw Manifests)
If you prefer deploying without Helm, example Kubernetes manifests are available:
Tarball with Systemd
Download the latest release tarball for your system from the Releases page. Tarballs include the binary and a Systemd service file.
The unit runs the HTTP transport on :8080 against the default --prometheus.url (http://127.0.0.1:9090); set other flags through their environment variables in the override, for example Environment=PROMETHEUS_MCP_PROMETHEUS_URL=https://prometheus.example.com:9090.
# extract the tarball and install the binary and unit file
# (<version> has no leading `v`, e.g. prometheus-mcp-0.19.0.linux-amd64.tar.gz)
tar -xzf prometheus-mcp-<version>.<os>-<arch>.tar.gz
cd prometheus-mcp-<version>.<os>-<arch>
install -m 0755 prometheus-mcp /usr/bin/prometheus-mcp
install -m 0644 prometheus-mcp.service /etc/systemd/system/
# create unit override and set any needed environment variables
systemctl edit prometheus-mcp.service
systemctl enable --now prometheus-mcp.service
Note: As of v0.19.0, releases no longer include system packages (deb, rpm, or Arch Linux .pkg.tar.zst); use the tarball instead.
Packages for v0.18.0 and earlier remain available on their release pages.
Security and Authentication
Connecting to Secure Prometheus Instances
The MCP server supports Prometheus HTTP config files to connect to secured Prometheus instances.
An example config can be found in the examples folder here.
Use the --http.config command-line flag to provide an HTTP configuration file.
If the file cannot be read or is invalid, the server exits at startup instead of falling back to an unauthenticated client.
Please see Flags for more information.
Forwarding Client Credentials
When using the HTTP transport, the MCP server forwards the Authorization header on each MCP request to Prometheus for that request's API calls.
Requests that carry no Authorization header, and all requests over the stdio transport, use the default client built from flags (see Connecting to Secure Prometheus Instances).
The server forwards client credentials to Prometheus as-is and does not validate them.
A credential that does not include an auth scheme is sent as a Bearer token.
Anyone who can reach the MCP endpoint can query Prometheus with at least the default client's credentials, so restrict access to the endpoint with a web configuration file or network-level controls.
Note that basic authentication in the web configuration file (basic_auth_users) conflicts with credential forwarding: the same Authorization header a client uses to authenticate to the MCP server is then forwarded to Prometheus in place of the default client's credentials.
TLS-only web configurations do not use the Authorization header and are unaffected.
Securing the MCP Server Endpoints
The MCP server supports Prometheus Web Configuration files files to expose it's endpoints behind optional basic auth and custom TLS configs.
Use the --web.config.file command-line flag to provide an HTTP configuration file.
Please see Flags for more information.
Telemetry
Health Endpoints
The web server exposes health endpoints on the configured listen address, following the /-/healthy and /-/ready convention used across the Prometheus ecosystem:
| Endpoint | Description |
|---|---|
/-/healthy |
Liveness: always returns 200 OK while the process is up and serving HTTP. |
/-/ready |
Readiness: returns 200 OK once the MCP transport is mounted and able to accept client sessions, and 503 Service Unavailable before that and during shutdown. |
These map directly onto Kubernetes liveness/readiness probes. The prom_mcp_server_ready metric reports the same readiness state.
Prometheus MCP questions
How do I add Prometheus MCP to Claude Code?
Run claude mcp add prometheus-mcp -- docker run -i --rm docker.io/prom/prometheus-mcp:v0.19.0-rc.0 in your terminal. Add --scope user to make it available in every project.
How do I add Prometheus MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Prometheus MCP provide?
It exposes 30 tools, including alertmanagers, build_info, clean_tombstones, config, delete_series.
Can I use this with other Prometheus compatible backends?
Yes, the server is designed to work with other Prometheus API compatible services like Thanos, Mimir, and Cortex.
How can I reduce token usage when querying metrics?
You can use TOON encoding to convert JSON data to a more token-efficient format, or enable API response truncation to limit the amount of data sent to the LLM.



