Skip to main content

Prometheus MCP Server

Python 3.12+ MCP License: Apache 2.0 Prometheus GitHub Discord

Prometheus is the backbone of cloud-native observability — but using it effectively requires deep expertise. Writing correct PromQL (especially counter semantics), deploying the right exporter for each system, wiring up ServiceMonitors, managing TSDB cardinality, and configuring remote-write are each a mini-specialization. If you want an AI assistant to help, it typically hallucinates metric names, ignores counter rules, or generates unsafe unbounded queries.

This server fixes that. It gives AI assistants (Claude, Cline, Cursor, or your own agent) structured, safe tools to operate Prometheus natively. Instead of guessing at PromQL or writing YAML from memory, your AI can now confidently manage the entire Prometheus lifecycle:

  1. Zero-to-One Application Onboarding. The AI recommends the right instrumentation strategy (direct library, exporter, or builtin metrics), generates ready-to-paste code snippets for Go/Java/Python/Node.js, validates the /metrics endpoint, and wires up a ServiceMonitor — all in one guided workflow.
  2. Safe PromQL Execution. Counter enforcement (counters must use rate()/increase()), automatic range-query downsampling to ~200 points per series, and query validation before execution.
  3. Exporter Lifecycle Management. A built-in catalog of 19 exporters with one-command Kubernetes deployment — including RBAC, ConfigMaps, DaemonSets, and multi-manifest orchestration.
  4. TSDB FinOps & Cardinality Control. Analyze top cardinality metrics, generate relabel configs to drop/keep labels, create recording rules, and configure remote-write to Thanos/Mimir/Cortex.
  5. Multi-Backend Support. Manage multiple Prometheus-compatible backends (Prometheus, Thanos, Mimir, Cortex, VictoriaMetrics) with explicit backend_id on every call.

Key Features​

Backend Discovery & Multi-Backend

  • Discover and inspect multiple Prometheus-compatible backends
  • Health checks, build info, feature flags, and runtime configuration
  • Supports Prometheus, Thanos, Mimir, Cortex, and VictoriaMetrics

PromQL Query Engine

  • Validate PromQL syntax before execution
  • Instant and range queries with counter enforcement
  • Automatic downsampling for range queries (100–200 points/series)
  • Natural language to PromQL translation via prom_suggest_promql

Application Onboarding

  • Recommend instrumentation strategy (direct, exporter, or builtin)
  • Generate code snippets for Go, Java, Python, Node.js
  • Validate /metrics endpoints for Prometheus/OpenMetrics format
  • Guided workflows for Kubernetes and VM/legacy environments

Exporter Lifecycle

  • 19-exporter catalog with deploy-ready configurations
  • One-command Kubernetes install (Deployment/DaemonSet + Service + RBAC)
  • End-to-end verification with polling (endpoint + up{} series check)

Rule Management & Simulation

  • Draft alert rules from natural language
  • Validate syntax via promtool check rules
  • Run unit tests with synthetic scenarios
  • Simulate historical firing against real data
  • Upsert rules to K8s CRDs with autonomous CRD discovery

TSDB FinOps & Optimization

  • Cardinality analysis with top-N hotspot detection
  • Generate metric_relabel_configs for label dropping/keeping
  • Create recording rules for pre-computing expensive queries
  • Configure remote-write to long-term storage backends

Governance & Security

  • Scoped access policies per backend (whitelist/blacklist/read-only)
  • In-memory audit log with filtering by backend, action, and time

Production-Ready Middleware

  • Response limiting (100KB max), rate limiting (10 req/s, burst 20)
  • Response caching, structured logging, error handling, timing

Architecture​

The server translates high-level MCP requests into Prometheus API and Kubernetes API calls through a layered service architecture.

How it works:

  1. An AI assistant connects via HTTP, SSE, or stdio
  2. The AI loads prom://system/backends resource to discover available backends
  3. Every subsequent tool call requires an explicit backend_id — no hidden state
  4. Service layers interact with Prometheus HTTP API and Kubernetes API
  5. Middleware enforces rate limiting, response size caps, and caching

Tech Stack​

CategoryTechnologies
LanguagePython 3.12+
MCP FrameworkFastMCP ≥2.13.3
ProtocolModel Context Protocol (MCP)
PrometheusHTTP API v1 · PromQL · ServiceMonitor CRDs
KubernetesPython K8s Client · RBAC · CRDs
TransportHTTP · SSE · Streamable-HTTP · stdio
InfrastructureDocker · uv

Quick Start​

You'll need access to a Prometheus-compatible backend (Prometheus, Thanos, Mimir, Cortex, or VictoriaMetrics), and optionally a Kubernetes cluster for exporter deployment and ServiceMonitor features.

Docker (recommended):

docker run --rm -it \
  -p 8767:8767 \
  -e PROMETHEUS_BASE_URL=http://host.docker.internal:9090 \
  -e MCP_TRANSPORT=http \
  talkopsai/prometheus-mcp-server:latest

Point your MCP client at it (e.g. in mcp.json or .cursor/mcp.json):

{
  "mcpServers": {
    "prometheus": {
      "url": "http://localhost:8767/mcp",
      "description": "MCP Server for Prometheus observability and monitoring management"
    }
  }
}

Security​

  • Never expose the MCP server to the public internet without proper authentication
  • Exporter deployments create real Kubernetes resources — review manifests before using prom_install_exporter
  • file_sd operations write to the local filesystem — ensure proper file permissions
  • Use governance access policies to restrict backend access per scope

Project Layout​

prometheus-mcp-server/
├── prometheus_mcp_server/
│   ├── tools/           # 28 MCP Tools across 10 categories
│   ├── resources/       # 14 MCP Resources (prom:// URIs)
│   ├── prompts/         # 5 Guided workflow prompts
│   ├── services/        # Prometheus + Kubernetes service wrappers
│   ├── server/          # FastMCP setup + 7-layer middleware stack
│   ├── utils/           # Exporter catalog, snippet generator, PromQL helpers
│   ├── models/          # Pydantic data models
│   ├── exceptions/      # Custom exception hierarchy
│   ├── config.py        # Environment parsing & exporter registry
│   └── main.py          # Entry point
├── tests/               # Test suites
├── docs/                # Workflow guides & test documentation
├── Dockerfile
├── pyproject.toml
└── README.md

Next Steps​

  • Configuration — Environment variables, Docker setup, multi-backend configuration
  • Tools — Full reference for all 28 MCP tools
  • Resources — 14 MCP resources for discovery, monitoring, and governance
  • Common Workflows — Step-by-step workflow guides
  • Examples — Quick reference and natural language prompts