alertmanagersLABSCO SUMMARY
The docs and runbooks are why the generated PromQL is usually right.
A model writing PromQL from memory gets the function names close and the semantics wrong. Embedding the official documentation and a set of guided workflows in the same server means it can look up the syntax and follow a known investigation path before querying. The destructive TSDB endpoints stay off unless you pass a flag whose name tells you exactly what you are agreeing to.
What it is
A Go server over the Prometheus HTTP API that returns the API's own JSON to the model. Alongside the API it embeds a pinned snapshot of the official Prometheus documentation and a set of guided runbooks for common tasks.
What you get
- Instant and range queries, exemplar queries, series lookup by matcher, label names and values, and metric metadata
- Target and alertmanager discovery, active alerts, and the alerting and recording rules currently loaded
- Server introspection: configuration, runtime flags, build and runtime info, health and readiness, TSDB cardinality statistics and WAL replay status
- The official Prometheus documentation listed, read and searched from inside the server
- Runbooks for system health checks, missing-data triage, error-rate investigation, high-cardinality work and rule review - offered as tools, as skill resources, and as MCP prompts
- Management endpoints for reload and shutdown, and the destructive TSDB admin tools behind an explicit dangerous flag
- An optional token-oriented output format and a response truncation limit for keeping replies small
Requirements
A reachable Prometheus, given with the URL flag or its environment variable; the default points at localhost on port 9090. Run a release binary, the container image, a system package with its bundled systemd unit, or the Helm chart on Kubernetes. Transport is stdio by default or streamable HTTP on the listen address, which defaults to port 8080 and also serves health endpoints and the server's own metrics. Secured Prometheus instances are reached with a Prometheus HTTP config file; the MCP endpoint itself can be put behind basic auth or TLS with a web config file.
Setup effort
One command — docker run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url "https://<YOUR_PROMETHEUS_HOST>:9090"
USE CASES
01
Answering a metrics question without writing PromQL
Find the metric and its labels first, then run the instant or range query the question actually needs.
02
Working out why queries got slow
Read the TSDB cardinality statistics and the series matching the suspect metric, then follow the high-cardinality runbook.
03
Reviewing the health of an instance
Read the configuration, flags, runtime and build info, target discovery and loaded rules in one pass.
04
Chasing missing data
Check target discovery and active alerts, then work the triage runbook rather than improvising.
05
Getting the syntax right
Search the embedded official documentation and read the relevant page before composing the query.
31 tools
Listed in project docs. Your client may show a different list.
build_infoconfigdocs_listdocs_readdocs_searchexemplar_queryflagshealthylabel_nameslabel_valueslist_alertslist_ruleslist_targetsmetric_metadataqueryquitrange_queryreadyreloadrunbooks_listrunbooks_readruntime_infoseriestargets_metadatatsdb_statswal_replay_statusclean_tombstonesdelete_seriessnapshotlist_storesBEFORE YOU INSTALL
What to know first
Tools you get
31 tools named in the project's documentation. clean_tombstones, delete_series and snapshot need --dangerous.enable-tsdb-admin-tools. list_stores appears only with --prometheus.backend=thanos, which removes seven others, and --mcp.tools narrows the set to eleven core tools plus your allowlist.
INSTALLATION
Connect your client
Server setup
Setup
Download a release appropriate for your system from https://github.com/tjhop/prometheus-mcp-server/releases
Run it, pointing at your Prometheus: <YOUR_PATH_TO_PROMETHEUS_MCP_SERVER> --prometheus.url "https://<YOUR_PROMETHEUS_HOST>:9090" (or set PROMETHEUS_MCP_SERVER_PROMETHEUS_URL)
docker
TERMINAL
docker run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest --prometheus.url "https://<YOUR_PROMETHEUS_HOST>:9090"MCP Clients
Any MCP client — stdio
The project publishes no per-client configuration ("Please check the documentation for the tool being used/integrated"). Add it to your client as a local stdio server in that client's own format: either the full path to the prometheus-mcp-server binary as the command, or docker with the arguments run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest — in both cases followed by --prometheus.url and your Prometheus URL.
