grafana-mcp

Stellt einen Teil der Grafana-API als MCP-Server (Model Context Protocol) bereit, mit Fokus auf die Abfrage von Logs in natürlicher Sprache. Das Hauptziel: Sagen Sie „Zeige mir Fehler-Logs vom api-Service der letzten 30 Minuten“ und erhalten Sie die tatsächlichen Log-Zeilen zurück — ohne LogQL, Labels oder Datenquellen-UIDs manuell verwalten zu müssen.

Log-Datenquellen, Loki-Labels und die Zuordnung von einem Servicenamen zu seiner hostenden Datenquelle/seinem Label werden auf der Festplatte zwischengespeichert, sodass wiederholte Aufrufe redundante Label-Scans überspringen.

한국어 문서 / Korean README

Installation & Einrichtung

npx (keine Installation erforderlich)

Fügen Sie Folgendes zu ~/.mcp.json hinzu.

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@seungje.jun/grafana-mcp"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

Aus Quellcode bauen

git clone https://github.com/ninanung/grafana-mcp.git
cd grafana-mcp
npm install
npm run build

{
  "mcpServers": {
    "grafana": {
      "command": "node",
      "args": ["/path/to/grafana-mcp/dist/cli.js"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

Starten Sie Claude Code neu, um die MCP-Tools zu aktivieren.

Authentifizierung

Eines der folgenden ist erforderlich. Sie werden in der unten stehenden Reihenfolge geprüft — das erste vorhandene gewinnt.

Alle Bearer-Token werden als Authorization: Bearer <token> gesendet. Dem Server ist es egal, um welche Art von Token es sich handelt — er wählt nur dasjenige aus, das gesetzt ist.

Umgebungsvariablen

Related MCP server: Log Analyzer MCP Server

Tools

Anwendungsbeispiel

Ein typischer Ablauf in natürlicher Sprache, orchestriert durch den MCP-Client:

1. Benutzer: „Zeige mir Fehler-Logs vom api-Service der letzten 30 Minuten.“

2. query_logs mit service: "api", level: "error", time_from: "now-30m" → der Server erkennt automatisch, welche Loki-Datenquelle das service="api"-Label besitzt und führt LogQL aus.

3. (Erster Aufruf) die Service → Datenquelle/Label-Zuordnung wird im Cache gespeichert; nachfolgende Aufrufe überspringen den Erkennungsschritt.

4. Benutzer: „Fasse diese Fehler nach Mustern zusammen.“ → derselbe Aufruf mit output: "summarize" gibt nach Mustern gruppierte Zählungen zurück.

5. Benutzer: „Welche anderen Services haben wir?“ → list_services gibt die vollständige Serviceliste zurück.

Wenn der Servicename einen Tippfehler enthält, zeigt query_logs ähnliche Übereinstimmungen an (z. B. Meinten Sie: checkout, checkout-api?).

Funktionsweise der automatischen Erkennung

query_logs wählt die Zieldatenquelle und das Label selbstständig aus:

1. Filtern aller Datenquellen auf Log-Typen (Loki/ES/CloudWatch/OpenSearch/Splunk).

2. Für jede Loki-Datenquelle /loki/api/v1/labels abrufen und zuerst gängige Service-Label-Kandidaten (service, service_name, app, app_name, application, container, job) durchlaufen, dann alle verbleibenden Labels.

3. Für jedes Kandidaten-Label dessen Werte abrufen und prüfen, ob der angeforderte service-Name in dieser Liste enthalten ist.

4. Wenn genau ein (datasource, label)-Paar übereinstimmt, dieses verwenden. Wenn mehrere übereinstimmen, datasource_uid zur Disambiguierung anfordern. Wenn keine übereinstimmen, Vorschläge für ähnliche Namen zurückgeben.

5. Die aufgelöste (service → ds_uid, label)-Zuordnung wird zwischengespeichert; refresh: true oder refresh_log_cache erzwingt eine erneute Erkennung.

Die automatische Erkennung unterstützt derzeit nur Loki. Für Elasticsearch / CloudWatch / Splunk-Datenquellen übergeben Sie datasource_uid und service_label explizit (und erwarten Sie nicht, dass LogQL-spezifische Filter angewendet werden).

Ausgabemodi

query_logs akzeptiert output:

• raw (Standard): <ISO-Zeitstempel> <Log-Zeile> — gut zum direkten Lesen in einem Terminal.

• summarize: gruppiert Zeilen nach normalisiertem Muster (Zahlen → N, UUIDs → UUID) mit Zählungen und einem Beispiel pro Muster. Verwenden, wenn Zeilen verrauscht oder zu zahlreich sind.

• json: strukturierte Objekte { ts, line, labels } — für nachgelagerte Tools.

Cache

• Log-Cache: persistent gespeichert unter ~/.grafana-mcp/log-cache.json. Mit der Grafana-Basis-URL als Schlüssel, damit mehrere Instanzen nicht kollidieren.

• Jede Kategorie hat ihre eigene TTL (Datenquellen / Labels / Label-Werte / Service-Auflösung) — siehe die Tabelle der Umgebungsvariablen oben.

• Eine zwischengespeicherte Service-Auflösung, die später fehlschlägt (z. B. Label wurde umbenannt), wird automatisch ungültig gemacht, sodass der nächste Aufruf eine erneute Erkennung durchführt.

• Verwenden Sie get_log_cache zum Überprüfen, refresh_log_cache zum Löschen und export_log_cache / import_log_cache zum Teilen mit Teamkollegen.

Cache-Speicherort & Zurücksetzen

Die Cache-Datei ist ein einfaches JSON-Dokument — sicher zu überprüfen, zu bearbeiten oder manuell zu sichern.

Sicherheit & Einschränkungen

• Schreibgeschützt: der Server stellt keinen Endpunkt bereit, der den Grafana-Zustand verändert. Kein Dashboard/Datenquellen-CRUD, keine Änderungen an Alarmen.

• Stdio-Logs: alle Logs gehen an stderr, wodurch der MCP-stdio-Kanal sauber bleibt.

• TLS-Überspringung: GRAFANA_TLS_SKIP_VERIFY=true setzt NODE_TLS_REJECT_UNAUTHORIZED=0 prozessweit. Nur für selbstsigniertes Grafana in vertrauenswürdigen Netzwerken verwenden.

• Keine Protokollierung von Geheimnissen: Authentifizierungs-Token werden niemals in Audit-Logs geschrieben.

Lizenz

MIT