A Go-based MCP server enabling LLMs to interact with Prometheus via PromQL queries, metric discovery, and integrated official documentation.
This project is a Go-based MCP (Model Context Protocol) server designed to bridge the interaction gap between Large Language Models and the Prometheus observability platform. By wrapping the complete Prometheus HTTP API, it empowers LLMs to execute instant and range PromQL queries, discover labels/series, and read alert and rule statuses. To enhance LLM interaction quality, the project embeds the prometheus/docs offline submodule and provides TOON (Token-Oriented Object Notation) encoding alongside response truncation mechanisms to significantly optimize token consumption.
Core Capabilities#
- Query & Discovery: Instant query (
query), range query (range_query), label names/values (label_names/label_values), series query (series), metadata (metric_metadata/targets_metadata) - Alerts & Rules: List alerts (
list_alerts), list rules (list_rules), Alertmanager cluster info (alertmanagers) - System & Config: Runtime config (
config), flags (flags), build info (build_info), runtime info (runtime_info), readiness/health checks (ready/healthy) - TSDB Admin (explicit enable required): Hot reload (
reload), graceful shutdown (quit), clean tombstones, delete series, create snapshot, TSDB stats, WAL replay status - Knowledge Base & Docs:
docs_list,docs_read,docs_searchtools for querying Prometheus official documentation - Token Efficiency: TOON encoding converts JSON to Token-Oriented Object Notation; response truncation supports global defaults and per-tool row/entry limits
- Security & Control: Tool whitelist (
--mcp.tools); HTTP config file for connecting to Prometheus with Basic Auth/TLS; Web config file for securing own endpoints
Architecture#
Standard Go project layout with cmd/prometheus-mcp-server/ as the main entry point, internal/ for internal implementation, pkg/ for reusable packages. Independently maintains charts/ (Helm OCI), packaging/systemd/ (system packages), and grafana/ (pre-built Dashboard).
Supports both Stdio (local CLI direct connection) and Streamable HTTP (with SSE, for containerized/remote deployment) transports. A flexible backend adaptation layer via --prometheus.backend dynamically adds/removes tools per backend—e.g., Thanos removes config/quit and adds list_stores. Offline docs are integrated via .gitmodules referencing the upstream prometheus/docs repo. The server itself exposes Prometheus metrics with a pre-built Grafana Dashboard for self-observability.
Deployment#
Binary: Download from Releases and run:
prometheus-mcp-server --prometheus.url "https://your-prometheus:9090"
Docker:
docker run --rm -i ghcr.io/tjhop/prometheus-mcp-server:latest \
--prometheus.url "https://your-prometheus:9090"
Helm Chart (Kubernetes):
helm install prometheus-mcp-server oci://ghcr.io/tjhop/charts/prometheus-mcp-server \
--version <version> --set prometheus.url=http://prometheus:9090
systemd: System packages with service files are available; install via apt install then systemctl enable --now.
Key Configuration#
All CLI flags support environment variables with prefix PROMETHEUS_MCP_SERVER_.
| Setting | CLI Flag | Description |
|---|---|---|
| Target instance | --prometheus.url | Prometheus address |
| Transport | --mcp.transport | stdio (default) or http |
| Listen address | --web.listen-address | HTTP mode listen port |
| Tool whitelist | --mcp.tools | Restrict tools exposed to LLM |
| Backend type | --prometheus.backend | prometheus (default), thanos, etc. |
| Dangerous ops | --dangerous.enable-tsdb-admin-tools | Enable TSDB admin tools |
| Client auth | --http.config | TLS/Auth config for backend Prometheus |
| Server auth | --web.config.file | Security config for MCP Server endpoints |
Use Cases#
- LLM-assisted ops troubleshooting: Let Claude/Gemini/Ollama directly query metrics to diagnose slow queries and analyze instance health
- SLO/Recording Rule suggestions: LLM analyzes metrics and auto-suggests Prometheus recording rules
- Prometheus best practices: LLM leverages built-in docs to answer metric/label naming conventions
- Multi-backend queries: Execute PromQL on Thanos and other compatible systems
- CI/CD & GitOps: Integrate observability into AI coding assistants and automation workflows via MCP
Licensed under Apache-2.0, developed and maintained by tjhop.