talkopsai/prometheus-mcp-server repository overview

⁠Prometheus MCP Server

A comprehensive Model Context Protocol (MCP) server that gives AI assistants the power to query, instrument, and manage Prometheus monitoring — from backend discovery to exporter deployment, PromQL execution, TSDB optimization, and governance. Supports Prometheus, Thanos, Mimir, Cortex, and VictoriaMetrics.

⁠✨ Features

• Safe PromQL Execution: Counter enforcement (counters must use rate()/increase()), automatic range-query downsampling to ~200 points per series, and query validation before execution.
• Application Onboarding: Recommend instrumentation strategy (direct library, exporter, or builtin metrics), generate code snippets for Go/Java/Python/Node.js, validate /metrics endpoints, and wire up ServiceMonitors.
• Exporter Lifecycle: Built-in catalog of 19 exporters with one-command Kubernetes deployment — including RBAC, ConfigMaps, DaemonSets, and multi-manifest orchestration.
• TSDB FinOps & Cardinality Control: Analyze top cardinality metrics, generate relabel configs, create recording rules, and configure remote-write to Thanos/Mimir/Cortex.
• Rule Management & Testing: Draft, upsert, delete, and simulate alerting and recording rules — with promtool validation and historical firing analysis baked in.
• Multi-Backend Support: Manage multiple Prometheus-compatible backends with explicit backend_id on every call — no hidden defaults.
• Governance & Security: Scoped access policies per backend (whitelist/blacklist/read-only) and in-memory audit logging.
• Production-Ready Middleware: Response limiting (100KB max), rate limiting (10 req/s, burst 20), response caching, structured logging, and error handling.

⁠🚀 How to Use This Image

This Docker image runs an MCP server that connects to your Prometheus-compatible backend(s). AI assistants (Claude, Cline, Cursor, or any MCP client) connect to the server over HTTP, SSE, or stdio.

⁠Running Standalone (HTTP Transport)

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

The server is now listening on http://localhost:8767/mcp.

Then configure your MCP client to connect:

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

⁠With Kubernetes Access

To enable exporter deployment and ServiceMonitor management, mount your kubeconfig:

docker run --rm -it \
  -p 8767:8767 \
  -v ~/.kube:/app/.kube:ro \
  -e PROMETHEUS_BASE_URL=http://host.docker.internal:9090 \
  -e K8S_KUBECONFIG=/app/.kube/config \
  -e MCP_TRANSPORT=http \
  talkopsai/prometheus-mcp-server:latest

⁠Multi-Backend Setup

Connect to multiple Prometheus-compatible backends simultaneously:

docker run --rm -it \
  -p 8767:8767 \
  -e MCP_TRANSPORT=http \
  -e PROMETHEUS_BACKENDS='[
    {"id": "prod", "base_url": "https://prom-prod.example.com", "type": "prometheus"},
    {"id": "staging", "base_url": "https://thanos-staging.example.com", "type": "thanos"}
  ]' \
  talkopsai/prometheus-mcp-server:latest

⁠🛠️ Configuration (Claude Desktop — Stdio)

To use this image over stdio transport directly inside Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "prometheus-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "PROMETHEUS_BASE_URL=http://host.docker.internal:9090",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "MCP_LOG_LEVEL=INFO",
        "talkopsai/prometheus-mcp-server:latest"
      ]
    }
  }
}

To include Kubernetes access, add volume and environment variable args:

{
  "mcpServers": {
    "prometheus-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/Users/YOUR_USERNAME/.kube:/app/.kube:ro",
        "-e", "PROMETHEUS_BASE_URL=http://host.docker.internal:9090",
        "-e", "K8S_KUBECONFIG=/app/.kube/config",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "MCP_LOG_LEVEL=INFO",
        "talkopsai/prometheus-mcp-server:latest"
      ]
    }
  }
}

Replace /Users/YOUR_USERNAME/.kube with your actual kubeconfig path (e.g. C:\Users\YourUser\.kube on Windows).

⁠⚙️ Environment Variables

⁠Server Configuration

⁠Prometheus Backend

⁠Kubernetes

⁠🏷️ Supported Tags

• latest — Latest stable release
• 0.1.0 — Initial release

⁠🔧 Available Tools (28 Total)

⁠PromQL Query Engine

Execute, validate, and explore Prometheus metrics with safety rails.

⁠Application Onboarding

Instrument apps and wire up scrape targets.

⁠Exporter Lifecycle

Deploy and manage 19 built-in exporters on Kubernetes.

⁠TSDB FinOps & Optimization

Analyze cardinality and generate optimization configs.

⁠Rule Management & Testing

Author, validate, and simulate alerting and recording rules.

⁠📖 Available Resources (14 URIs)

The server exposes discoverable MCP resources that AI assistants read for context:

⁠🔐 Security Best Practices

1. Never expose the MCP server to the public internet without proper authentication.
2. Read-Only Mount: Always mount kubeconfig with :ro so the container cannot modify your credentials.
3. RBAC Least Privilege: Ensure the kubeconfig identity has only the permissions needed for exporter and ServiceMonitor operations.
4. Review Before Apply: TSDB FinOps tools generate YAML only — they do NOT apply changes. Exporter tools create real K8s resources, so review first.
5. Governance: Use scoped access policies to restrict backends to read-only or whitelist specific operations.

⁠🐳 Docker Compose Example

services:
  prometheus-mcp-server:
    image: talkopsai/prometheus-mcp-server:latest
    ports:
      - "8767:8767"
    environment:
      - PROMETHEUS_BASE_URL=http://prometheus:9090
      - MCP_TRANSPORT=http
      - MCP_LOG_LEVEL=INFO
    depends_on:
      - prometheus

  prometheus:
    image: prom/prometheus:latest
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml

⁠🔗 Links and Resources

• Source Code: GitHub Repository⁠
• Full Documentation: README & Guides⁠
• Model Context Protocol: MCP Official Site⁠
• Prometheus: Prometheus Documentation⁠
• Report Issues: GitHub Issues⁠
• Discord: Join the Community⁠
• License: Apache 2.0⁠

If you find this MCP server useful, consider leaving a ⭐ on the GitHub repository⁠!