prometheus-mcp

MCP-Server für Prometheus Metriken und Observability. Geben Sie Claude (oder einem beliebigen MCP-fähigen Agenten) Lesezugriff auf Ihre Prometheus-Instanz — fragen Sie Metriken mit PromQL ab, untersuchen Sie aktive Alarme und erkunden Sie Scrape-Targets —, ohne das Gespräch zu verlassen.

Warum ein weiteres Prometheus MCP?

Die bestehenden Prometheus-Integrationen erfordern benutzerdefinierte Skripte oder direktes API-Wissen. Dieser Server:

• Spricht das Standard Model Context Protocol über stdio — funktioniert mit Claude Desktop, Claude Code, Cursor und jedem MCP-Client.

• Ist schreibgeschützt: alle 5 Tools tragen readOnlyHint: true — kein Risiko, Prometheus-Daten zu verändern.

• Liefert Dual-Channel-Ausgabe: strukturiertes JSON (structuredContent) für die programmatische Nutzung + Markdown (content) für die menschenlesbare Anzeige.

• Hat umsetzbare Fehlermeldungen, die die genaue Umgebungsvariable nennen, die korrigiert werden muss, und einen nächsten Schritt vorschlagen.

• Unterstützt Bearer-Token, HTTP Basic Auth oder keine Authentifizierung (üblich für interne Bereitstellungen).

Tools

Installation

pip install prometheus-mcp

Oder führen Sie es direkt ohne Installation aus:

uvx prometheus-mcp

Konfiguration

Die gesamte Konfiguration erfolgt über Umgebungsvariablen:

Kopieren Sie .env.example nach .env und tragen Sie Ihre Werte ein.

Claude Desktop / Claude Code Einrichtung

Fügen Sie dies zu Ihrer MCP-Konfiguration hinzu (claude_desktop_config.json oder .claude/mcp.json):

{
  "mcpServers": {
    "prometheus": {
      "command": "prometheus-mcp",
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com",
        "PROMETHEUS_TOKEN": "your-token-here"
      }
    }
  }
}

Oder mit uvx (keine Installation erforderlich):

{
  "mcpServers": {
    "prometheus": {
      "command": "uvx",
      "args": ["prometheus-mcp"],
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com"
      }
    }
  }
}

Docker

docker run --rm -e PROMETHEUS_URL=https://prometheus.example.com prometheus-mcp

Beispielabfragen

Sobald die Konfiguration abgeschlossen ist, fragen Sie Claude:

• "Welche Metriken hat Prometheus über HTTP-Anfragen?"

• "Wie hoch ist die aktuelle Anfragerate für den Zahlungsdienst?"

• "Zeige mir die CPU-Auslastung der letzten Stunde mit einer Auflösung von 5 Minuten"

• "Gibt es aktive Alarme? Wie hoch ist deren Schweregrad?"

• "Welche Scrape-Targets sind derzeit ausgefallen und warum?"

• "Wie viele node-exporter-Instanzen laufen?"

Tool-Nutzungsanleitung

prometheus_list_metrics

Gibt alle Metriknamen zurück, die Prometheus kennt. Verwenden Sie pattern, um nach Substrings zu filtern (Groß-/Kleinschreibung wird ignoriert). Starten Sie hier, wenn Sie nicht wissen, welche Metriken verfügbar sind. Die Ausgabe ist auf 500 Metriken mit einem Kürzungshinweis begrenzt.

prometheus_query

Führt einen sofortigen PromQL-Ausdruck aus und erhält aktuelle Werte. Gibt den Ergebnistyp (Vektor/Skalar/Matrix/String), die Stichprobenanzahl sowie Labels und Werte pro Stichprobe zurück.

Parameter:

• query (erforderlich) — PromQL-Ausdruck, z. B. up, rate(http_requests_total[5m])

• time (optional) — RFC3339 oder Unix-Zeitstempel; Standard ist jetzt

prometheus_query_range

Führt einen PromQL-Ausdruck über ein Zeitfenster aus. Gibt eine Reihe pro passender Zeitreihe mit zeitgestempelten Werten zurück. Die Gesamtzahl der Datenpunkte über alle Reihen ist auf 5000 begrenzt.

Parameter:

• query (erforderlich) — PromQL-Ausdruck

• start / end (erforderlich) — RFC3339 oder Unix-Zeitstempel

• step (erforderlich) — Auflösung wie 15s, 1m, 5m

Prometheus lehnt Schritte ab, die > 11.000 Punkte pro Reihe erzeugen würden (HTTP 422). Erhöhen Sie den Schritt oder verengen Sie den Bereich, falls dies passiert.

Hinweis: Die Prometheus-Bereichs-API unterstützt keine Filterung nach Branch oder Commit — Filter werden rein in PromQL-Label-Matchern ausgedrückt.

prometheus_list_alerts

Gibt alle aktiven/ausstehenden Alarme mit Labels (einschließlich alertname, severity), Status, Aktivierungszeit und aktuellem Wert zurück. Enthält eine Statuszusammenfassung (Anzahl der auslösenden vs. ausstehenden Alarme).

prometheus_list_targets

Gibt Scrape-Targets mit Jobname, Instanzadresse, Status (up/down/unknown), letzter Scrape-Dauer in Millisekunden und eventuellen Fehlermeldungen zurück. Enthält eine Zusammenfassung pro Job. Filtern Sie nach state: active (Standard), dropped oder any.

Leistungsmerkmale

• Alle Tools verwenden eine einzelne persistente requests.Session mit Verbindungspooling.

• Die Sitzung hat trust_env = False, um Umgebungsproxys zu umgehen (Prometheus ist normalerweise ein interner Dienst).

• Anfragen haben ein Timeout von 30 Sekunden.

• prometheus_query_range begrenzt die Ausgabe auf insgesamt 5000 Punkte über alle Reihen — verwenden Sie einen größeren Schritt für lange Zeitfenster.

• prometheus_list_metrics gibt nach dem Filtern bis zu 500 Metriken zurück.

Entwicklung

git clone https://github.com/mshegolev/prometheus-mcp
cd prometheus-mcp
pip install -e '.[dev]'
pytest tests/ -v
ruff check src tests
ruff format src tests

Lizenz

MIT — siehe LICENSE.