Grafana

offiziell

Dashboards durchsuchen, Vorfälle untersuchen und Datenquellen in Ihrer Grafana-Instanz abfragen

Was kann man mit Grafana MCP machen?

  • Dashboards suchen und untersuchen — Dashboards nach Titel, Ordner, Tag oder Favoritenstatus finden und anschließend eine kompakte Zusammenfassung oder bestimmte Eigenschaften per JSONPath abrufen.
  • Prometheus und Loki abfragen — PromQL-Metrikabfragen und LogQL-Log- oder Metrikabfragen ausführen sowie Metadaten wie Metriknamen, Labels und Log-Muster abrufen.
  • SQL-Datenquellen abfragen — Datenbanken, Schemas und Tabellen auflisten, Spalten beschreiben und SQL für ClickHouse, Snowflake, Athena, PostgreSQL und andere ausführen.
  • Alerting verwalten — Alert-Regeln mit Auslösestatus auflisten, Regeln erstellen oder aktualisieren sowie Benachrichtigungsrichtlinien und Kontaktpunkte anzeigen.
  • Deeplinks generieren — Präzise URLs für Dashboards, Panels und Explore mit Zeitbereichen und benutzerdefinierten Parametern erstellen, statt zu raten.
  • Panels und Dashboards rendern — PNG-Bilder eines Panels oder eines vollständigen Dashboards mit benutzerdefinierten Abmessungen, Zeitbereich, Design und Variablen erzeugen.

Dokumentation

Grafana MCP-Server

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

Ein Model Context Protocol (MCP)-Server für Grafana.

Dieser ermöglicht den Zugriff auf Ihre Grafana-Instanz und das zugehörige Ökosystem.

Schnellstart

Erfordert uv. Fügen Sie Ihrer MCP-Client-Konfiguration (z. B. Claude Desktop, Cursor) Folgendes hinzu:

{
  "mcpServers": {
    "grafana": {
      "command": "uvx",
      "args": ["mcp-grafana"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Ersetzen Sie für Grafana Cloud GRAFANA_URL durch die URL Ihrer Instanz (z. B. https://myinstance.grafana.net). Unter Verwendung finden Sie weitere Installationsoptionen, darunter Docker, Binärdatei und Helm.

Anforderungen

  • Für den vollen Funktionsumfang ist Grafana Version 9.0 oder höher erforderlich. Einige Funktionen, insbesondere Vorgänge im Zusammenhang mit Datenquellen, funktionieren aufgrund fehlender API-Endpunkte mit älteren Versionen möglicherweise nicht korrekt.

Funktionen

Die folgenden Funktionen sind derzeit im MCP-Server verfügbar. Diese Liste dient nur zu Informationszwecken und stellt weder eine Roadmap noch eine Zusage für zukünftige Funktionen dar.

Dashboards

  • Dashboards suchen: Dashboards nach Titel, Ordner-UID, Tag oder Markierungsstatus finden
  • Dashboard anhand der UID abrufen: Vollständige Dashboard-Details anhand der eindeutigen Kennung abrufen. Übergeben Sie optional version, um statt des aktuellen Dashboards einen gespeicherten Snapshot zu laden. Warnung: Große Dashboards können viel Kontextfensterplatz beanspruchen.
  • Dashboard-Versionen auflisten: Gespeicherte Versionen eines Dashboards als kompakte Metadaten auflisten (Versionsnummer, Autor, Zeitstempel, Speichernachricht)
  • Dashboard-Zusammenfassung abrufen: Eine kompakte Übersicht über ein Dashboard mit Titel, Anzahl der Panels, Paneltypen, Variablen und Metadaten abrufen, ohne das vollständige JSON zu laden, um den Kontextfensterverbrauch zu minimieren
  • Dashboard-Eigenschaft abrufen: Bestimmte Teile eines Dashboards mithilfe von JSONPath-Ausdrücken extrahieren (z. B. $.title, $.panels[*].title), um nur benötigte Daten abzurufen und den Kontextfensterverbrauch zu reduzieren
  • Dashboard aktualisieren oder erstellen: Vorhandene Dashboards ändern oder neue erstellen. Warnung: Dafür ist das vollständige Dashboard-JSON erforderlich, das viel Kontextfensterplatz beanspruchen kann.
  • Dashboard patchen: Bestimmte Änderungen an einem Dashboard vornehmen, ohne das vollständige JSON zu benötigen. Dadurch wird der Kontextfensterverbrauch bei gezielten Änderungen deutlich reduziert.
  • Panel-Abfragen und Datenquelleninformationen abrufen: Titel, Abfragezeichenfolge und Datenquelleninformationen (einschließlich UID und Typ, sofern verfügbar) aller Panels eines Dashboards abrufen

Panel-Abfrage ausführen

Hinweis: Tools zum Ausführen von Panel-Abfragen sind standardmäßig deaktiviert. Fügen Sie zum Aktivieren runpanelquery zu Ihrem --enabled-tools-Flag hinzu.

  • Panel-Abfrage ausführen: Die Abfrage eines Dashboard-Panels mit benutzerdefinierten Zeitbereichen und Variablenüberschreibungen ausführen. Infinity-Panels werden ausgeführt, wenn die Abfrage den Parser backend oder jq-backend verwendet (Google-Sheets-Abfragen verwenden immer einen dieser Parser); der Standardparser simple sowie die Parser UQL und GROQ funktionieren nur im Browser. Neo4j-Panels des Plugins kniepdennis-neo4j-datasource führen ihre Cypher-Abfrage über das Plugin aus, das schreibgeschützte Sitzungen öffnet. Elasticsearch-Panels interpolieren Variablen in der Lucene-Abfrage im Format lucene, wie Grafana es tut. Automatische Datums-Histogramme verwenden dasselbe Intervall wie $__interval.

Kontextfenster verwalten

Die Dashboard-Tools bieten jetzt mehrere Strategien, um den Kontextfensterverbrauch effektiv zu verwalten (Issue #101):

  • Verwenden Sie get_dashboard_summary für eine Dashboard-Übersicht und die Planung von Änderungen
  • Verwenden Sie get_dashboard_property mit JSONPath, wenn Sie nur bestimmte Dashboard-Teile benötigen
  • Vermeiden Sie get_dashboard_by_uid, sofern Sie nicht ausdrücklich das vollständige Dashboard-JSON benötigen

Datenquellen

  • Datenquellen auflisten und Informationen abrufen: Alle konfigurierten Datenquellen anzeigen und detaillierte Informationen zu jeder einzelnen abrufen.
    • Unterstützte Datenquellentypen: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.
  • Datenquellenressourcen: Jede Datenquelle, auf die Sie zugreifen können, wird auch als MCP-Ressource unter grafana://datasources/{uid} bereitgestellt. So können Sie sie direkt an eine Unterhaltung anhängen (zum Beispiel mit @ in Claude Code), statt sie vom Modell suchen zu lassen. Zusammen mit den Datenquellen-Tools deaktiviert.

Abfragebeispiele

Hinweis: Tools für Abfragebeispiele sind standardmäßig deaktiviert. Fügen Sie zum Aktivieren examples zu Ihrem --enabled-tools-Flag hinzu.

  • Abfragebeispiele abrufen: Beispielabfragen für verschiedene Datenquellentypen abrufen, um die Abfragesyntax kennenzulernen.

Prometheus-Abfragen

  • Prometheus abfragen: PromQL-Abfragen (sowohl sofortige als auch zeitbereichsbasierte Metrikabfragen) für Prometheus-Datenquellen ausführen.
  • Prometheus-Metadaten abfragen: Metrikmetadaten, Metriknamen, Labelnamen und Labelwerte aus Prometheus-Datenquellen abrufen.
  • Histogramm-Perzentile abfragen: Histogramm-Perzentilwerte (p50, p90, p95, p99) mithilfe von histogram_quantile berechnen.

Loki-Abfragen

  • Loki-Protokolle und -Metriken abfragen: Sowohl Protokoll- als auch Metrikabfragen mit LogQL für Loki-Datenquellen ausführen.
  • Loki-Metadaten abfragen: Labelnamen, Labelwerte und Stream-Statistiken aus Loki-Datenquellen abrufen.
  • Loki-Muster abfragen: Von Loki erkannte Protokollmuster abrufen, um häufige Protokollstrukturen und Anomalien zu identifizieren.

InfluxDB-Abfragen

Hinweis: InfluxDB-Tools sind standardmäßig deaktiviert. Fügen Sie zum Aktivieren influxdb zu Ihrem --enabled-tools-Flag hinzu.

  • InfluxDB abfragen: Abfragen für InfluxDB-Datenquellen mit InfluxQL (v1.x) oder Flux (v2.x) ausführen. Der Dialekt wird aus der Datenquellenkonfiguration abgeleitet oder kann explizit über den Parameter dialect festgelegt werden.

SQL-Datenquellen abfragen

Hinweis: SQL-Tools sind standardmäßig deaktiviert. Fügen Sie zum Aktivieren sql zu Ihrem --enabled-tools-Flag hinzu. Die Abwärtskompatibilitäts-Aliase clickhouse, snowflake und athena funktionieren ebenfalls.

Einheitliche SQL-Tools unterstützen ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL und BigQuery über einen einzigen Werkzeugsatz. Abfragen werden über die Datenquellen-Plugins von Grafana ausgeführt. Die Authentifizierung erfolgt daher über die Datenquellenkonfiguration – Anmeldedaten sind für den MCP-Server niemals sichtbar.

  • Datenbanken/Schemas/Kataloge auflisten: Organisationseinheiten einer SQL-Datenquelle ermitteln. Bei Athena lassen Sie den Katalog weg, um Kataloge aufzulisten, oder übergeben Sie einen Katalog, um Datenbanken aufzulisten.
  • Tabellen auflisten: Tabellen in einer Datenbank oder einem Schema mit Metadaten auflisten (Zeilenanzahl und, sofern verfügbar, Größen).
  • Tabellenschema beschreiben: Spaltennamen, Typen, NULL-Zulässigkeit, Standardwerte und Kommentare abrufen.
  • SQL abfragen: SQL-Abfragen mit datenquellenspezifischer Makrosubstitution ($__timeFilter(col), $__from/$__to, $__interval, ${varname}), automatischer Begrenzung der Ergebnismenge und Unterstützung für Vorlagenvariablen ausführen.

Konfigurieren Sie für BigQuery das Plugin grafana-bigquery-datasource in Grafana. Für die Ermittlung werden database für das Projekt und schema für das Dataset verwendet. Wenn database nicht angegeben ist, wird standardmäßig zuerst die Datenquelle defaultProject und anschließend der Endpunkt /defaultProjects des Plugins verwendet (einschließlich der Projektermittlung über GCE). Metadaten werden ausschließlich über APIs abgerufen, ohne Abfragejobs oder Tabellenscans. Spaltenbeschreibungen und verschachtelte Typen sind enthalten; das Plugin lässt Tabellenbeschreibungen und -typen, die NULL-Zulässigkeit von Spalten sowie Standardwerte aus.

BigQuery-Abfragen erfordern qualifizierte Tabellenreferenzen wie `my-project.my_dataset.fct_events` and use the datasource's billing project. Optional location defaults to datasource processingLocation. Use ${name:sqlstring} für maskierte Zeichenfolgenvariablen. Zeilenbegrenzungen beschränken weder die gescannten Bytes noch die Abfragekosten.

CloudWatch-Abfragen

Hinweis: CloudWatch-Tools sind standardmäßig deaktiviert. Fügen Sie zum Aktivieren cloudwatch zu Ihrem --enabled-tools-Flag hinzu.

  • CloudWatch-Namespaces auflisten: Verfügbare AWS-CloudWatch-Namespaces ermitteln.
  • CloudWatch-Metriken auflisten: Metriken auflisten, die in einem bestimmten Namespace verfügbar sind.
  • CloudWatch-Dimensionen auflisten: Dimensionen zum Filtern von Metrikabfragen abrufen.
  • CloudWatch abfragen: CloudWatch-Metrikabfragen mit Unterstützung für Zeitbereiche ausführen.
  • CloudWatch-Protokollgruppen auflisten: Protokollgruppen ermitteln, optional nach Namenspräfix gefiltert.
  • Felder von CloudWatch-Protokollgruppen auflisten: Verfügbare Felder einer Protokollgruppe ermitteln.
  • CloudWatch Logs abfragen: CloudWatch-Logs-Insights-Abfragen für eine oder mehrere Protokollgruppen ausführen.

Google-Cloud-Logging-Abfragen

Hinweis: Google-Cloud-Logging-Tools sind standardmäßig deaktiviert. Fügen Sie zum Aktivieren cloudlogging zu Ihrem --enabled-tools-Flag hinzu. Erfordert das Google-Cloud-Logging-Datenquellen-Plugin (googlecloud-logging-datasource) in Version 1.8.0 oder höher, das Grafana 11.2+ voraussetzt. Ältere Plugin-Versionen liefern ein anderes Antwortlayout, und query_cloud_logging meldet einen Fehler mit der Aufforderung zum Upgrade.

  • Cloud-Logging-Projekte auflisten: GCP-Projekt-IDs ermitteln, aus denen die Datenquelle Protokolle lesen kann.
  • Cloud-Logging-Buckets und -Ansichten auflisten: Protokoll-Buckets und -Ansichten ermitteln, um den Abfragebereich einzugrenzen.
  • Cloud Logging abfragen: Filter der Cloud-Logging-Abfragesprache (z. B. resource.type="k8s_container" AND severity>=ERROR) mit Zeitbereich und Begrenzung ausführen. Die Einträge werden absteigend nach Zeit sortiert zurückgegeben und enthalten Schweregrad, Textkörper, Labels und Trace-ID. Die GCP-Authentifizierung erfolgt über die Datenquellenkonfiguration.

Azure-Monitor-Abfragen

Hinweis: Azure-Monitor-Tools sind standardmäßig deaktiviert. Fügen Sie zum Aktivieren azuremonitor zu Ihrem --enabled-tools-Flag hinzu. Die Abfragen werden über eine Azure-Monitor-Datenquelle (grafana-azure-monitor-datasource) ausgeführt; die Azure-Authentifizierung erfolgt über die Datenquellenkonfiguration.

  • Azure Log Analytics abfragen: KQL für einen oder mehrere Log-Analytics-Arbeitsbereiche oder Ressourcen mit Zeitbereich und Begrenzung ausführen; Spalten und Zeilen werden zurückgegeben.
  • Azure Resource Graph abfragen: Resource-Graph-KQL ausführen, um Azure-Ressourcen und ihren aktuellen Status abonnementübergreifend zu inventarisieren.

Graphite-Abfragen

Hinweis: Graphite-Tools sind standardmäßig deaktiviert. Fügen Sie zum Aktivieren graphite zu Ihrem --enabled-tools-Flag hinzu.

  • Graphite abfragen: Abfragen der Graphite-Render-API für eine Graphite-Datenquelle ausführen.
  • Graphite-Metriken auflisten: Graphite-Metrikpfade durchsuchen und ermitteln.
  • Graphite-Tags auflisten: Verfügbare Graphite-Tags und Tag-Werte auflisten.
  • Graphite-Dichte abfragen: Die Graphite-Metrikdichte für ein bestimmtes Muster abfragen.

Elasticsearch-/OpenSearch-Abfragen

Hinweis: Elasticsearch-/OpenSearch-Tools sind standardmäßig deaktiviert. Fügen Sie zum Aktivieren elasticsearch zu Ihrem --enabled-tools-Flag hinzu.

  • Elasticsearch/OpenSearch abfragen: Suchabfragen für Elasticsearch- oder OpenSearch-Datenquellen mit Lucene-Abfragesyntax oder Elasticsearch Query DSL ausführen. Unterstützt das Filtern nach Zeitbereich und das Abrufen von Protokollen, Metriken oder beliebigen indizierten Daten. Gibt Dokumente mit Index, ID, Quellfeldern und optionaler Relevanzbewertung zurück.

Quickwit-Abfragen

Hinweis: Quickwit-Tools sind standardmäßig deaktiviert. Fügen Sie zum Aktivieren quickwit zu Ihrem --enabled-tools-Flag hinzu.

  • Quickwit abfragen: Suchabfragen für Quickwit-Datenquellen mit Lucene-Abfragesyntax oder einer teilweise Elasticsearch-kompatiblen Query DSL ausführen. Unterstützt das Filtern nach Zeitbereich und das Abrufen von Protokollen oder anderen indizierten Dokumenten. Gibt Dokumente mit Index, ID, Quellfeldern und optionaler Relevanzbewertung zurück.

Agentenbeobachtbarkeit

Hinweis: Tools für die Agentenbeobachtbarkeit sind standardmäßig deaktiviert und funktionieren nur in Grafana Cloud. Fügen Sie zum Aktivieren agento11y zu Ihrem --enabled-tools-Flag hinzu.

  • Unterhaltungen auflisten und durchsuchen: Aktuelle LLM-Unterhaltungen auflisten oder sie mit einem Filterausdruck (Modell, Anbieter, Agent, Status, Fehlertyp, Evaluierungsergebnisse und mehr) innerhalb eines Zeitraums durchsuchen. Die Suchergebnisse enthalten Fehleranzahlen, Bewertungsübersichten, Evaluierungsübersichten und Trace-IDs.
  • Unterhaltungsdetails abrufen: Eine einzelne Unterhaltung mit all ihren Generierungen einschließlich Prompts und Ausgaben abrufen.
  • Generierungsdetails und Bewertungen abrufen: Eine einzelne Generierung anhand ihrer ID sowie ihre Evaluierungsbewertungen abrufen (Evaluator, Bewertungsschlüssel, Wert, bestanden, Erklärung).
  • Agentenkatalog lesen: Die Agents auflisten, die Telemetriedaten senden, eine Agentenversion vollständig abrufen (vollständiger System-Prompt, jedes Tool mit seinem JSON-Schema und die verwendeten Modelle), den Versionsverlauf eines Agents durchgehen und aggregierte Evaluierungsbewertungen pro Version vergleichen. Effektive Versionen sind sha256:-Hashes, die von einer Tooländerung nicht beeinflusst werden. Für einen Agent, der keine eigene Version meldet, wird der System-Prompt gehasht, sodass eine Promptänderung eine neue Version erzeugt. Katalog- und Versionszeilen enthalten ein token_estimate, das vor dem Abrufen eines vollständigen Prompts geprüft werden sollte.
  • Evaluatoren und Vorlagen prüfen: Die Evaluatoren lesen, aus denen eine Bewertung stammt, die Vorlagen, von denen sie abgeleitet wurden, sowie die für LLM-Judge-Evaluatoren verfügbaren Judge-Anbieter und -Modelle. Wenn Schreibtools aktiviert sind, können Evaluatoren außerdem erstellt, abgeleitet, getestet und gelöscht werden.
  • Evaluierungsregeln und Schutzmechanismen prüfen: Die asynchronen Evaluierungsregeln lesen, die Evaluatoren an Produktionsdatenverkehr binden, sowie die Schutzmechanismen (Hook-Regeln), die inline ausgeführt werden und warnen oder ablehnen können. Wenn Schreibtools aktiviert sind, können sie außerdem erstellt, aktualisiert, in der Vorschau angezeigt und gelöscht werden. Schreibvorgänge sowie die nicht persistierenden Vorgänge preview_rule und test_evaluator benötigen die Berechtigung grafana-agento11y-app.eval:write, die von der Rolle Agento11y Admin gewährt wird.
  • Gespeicherte Unterhaltungen und Sammlungen kuratieren: Die gespeicherten Unterhaltungen lesen (Lesezeichen, die einer Unterhaltung eine stabile ID, einen Namen und Tags geben) sowie die Sammlungen, in denen sie gruppiert sind, einschließlich der Mitgliederanzahl jeder Sammlung und der in jeder Zeile einer gespeicherten Unterhaltung eingebetteten Sammlungen. Wenn Schreibtools aktiviert sind, können außerdem Unterhaltungen mit Lesezeichen versehen, Sammlungen erstellt und bearbeitet sowie Mitglieder hinzugefügt oder entfernt werden. Für diese Schreibvorgänge ist dieselbe Berechtigung grafana-agento11y-app.eval:write erforderlich.
  • Testsuiten lesen und bearbeiten: Die versionierten Testsuiten auflisten, mit denen Offline-Experimente ausgeführt werden, eine Suite mit ihrem vollständigen Versionsverlauf lesen und die Testfälle einer Version seitenweise abrufen. Wenn Schreibtools aktiviert sind, können außerdem eine Suite erstellt, umbenannt oder mit neuen Tags versehen, eine Entwurfsversion geöffnet, diese veröffentlicht sowie ihre Testfälle geschrieben oder gelöscht werden. Eine veröffentlichte Version ist unveränderlich; für eine Bearbeitung muss daher ein neuer Entwurf geöffnet werden. Für diese Schreibvorgänge ist grafana-agento11y-app.eval:write erforderlich.
  • Offline-Experimente lesen: Die Evaluierungsläufe für eine Testsuite auflisten und einen Lauf mit seiner zusammenfassenden Erfolgsrate, den Kosten und den Token-Gesamtzahlen lesen. Einen Bericht pro Testfall aufrufen, um die Durchläufe, ihre Bewertungen mit den Erklärungen der einzelnen Judges und ihre Artefaktmetadaten einzusehen. Wenn Schreibtools aktiviert sind, können Experimente außerdem umbenannt oder mit neuen Tags versehen und laufende Experimente abgebrochen werden; dafür ist grafana-agento11y-app.eval:write erforderlich. Experimente werden von SDK-Runnern erstellt, nicht von diesem Tool.

Grafana Assistant

Hinweis: Assistant-Tools sind standardmäßig deaktiviert und erfordern, dass das Plugin Grafana Assistant (grafana-assistant-app) auf der Zielinstanz von Grafana installiert ist. Sie sind außerdem Schreibtools (der Assistant kann den Stack-Zustand ändern) und werden daher übersprungen, wenn --disable-write gesetzt ist. Um sie zu aktivieren, füge assistant zu deinem --enabled-tools-Flag hinzu.

  • Den Assistant fragen: Einen Prompt in natürlicher Sprache an Grafana Assistant senden und auf die vollständige Textantwort warten. Der Assistant kann Tools, Metriken, Logs und weiteren Stack-Kontext verwenden – mehr als bei einer einzelnen, isolierten Abfrage einer Datenquelle. Den zurückgegebenen Wert contextId in einem Folgeaufruf übergeben, um dieselbe Unterhaltung fortzusetzen. Komplexe Aufgaben können mehrere Minuten dauern; der Aufruf blockiert, bis die Antwort fertig ist oder die Anfrage abläuft (5 Minuten).

Incidents

  • Incidents suchen, erstellen und aktualisieren: Incidents in Grafana Incident verwalten, einschließlich Suchen, Erstellen, Hinzufügen von Aktivitäten sowie Lesen oder Festlegen benutzerdefinierter Felder.
  • Incident-Ressourcen: Aktive Incidents, die in den letzten 30 Tagen begonnen haben, sind auch als MCP-Ressourcen unter grafana://irm/incidents/{id} verfügbar, sodass du einen Incident direkt an eine Unterhaltung anhängen kannst (zum Beispiel mit @ in Claude Code). Zusammen mit den Incident-Tools deaktiviert.

Alerting

  • Informationen zu Alert-Regeln auflisten und abrufen: Alert-Regeln und ihren Status (ausgelöst/normal/Fehler usw.) in Grafana anzeigen. Unterstützt sowohl von Grafana verwaltete Regeln als auch von Datenquellen verwaltete Regeln aus Prometheus- oder Loki-Datenquellen.
  • Alert-Regeln erstellen und aktualisieren: Neue Alert-Regeln erstellen oder vorhandene ändern.
  • Alert-Regeln löschen: Alert-Regeln anhand ihrer UID entfernen.
  • Alert-Routing verwalten: Benachrichtigungsrichtlinien, Kontaktpunkte und Zeitintervalle anzeigen. Unterstützt sowohl von Grafana verwaltete Kontaktpunkte als auch Empfänger aus externen Alertmanager-Datenquellen (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

  • Zeitpläne auflisten und verwalten: Bereitschaftspläne in Grafana OnCall anzeigen und verwalten.
  • Schichtdetails abrufen: Detaillierte Informationen zu bestimmten Bereitschaftsschichten abrufen.
  • Aktuelle Bereitschaftsnutzer abrufen: Anzeigen, welche Nutzer für einen Zeitplan derzeit Bereitschaft haben.
  • Teams und Nutzer auflisten: Alle OnCall-Teams und -Nutzer anzeigen.
  • Alert-Gruppen auflisten: Alert-Gruppen aus Grafana OnCall anhand verschiedener Kriterien wie Status, Integration, Labels und Zeitraum anzeigen und filtern.
  • Details zu Alert-Gruppen abrufen: Detaillierte Informationen zu einer bestimmten Alert-Gruppe anhand ihrer ID abrufen.

Admin

Hinweis: Admin-Tools sind standardmäßig deaktiviert. Um sie zu aktivieren, füge admin zu deinem --enabled-tools-Flag hinzu.

  • Teams auflisten: Alle konfigurierten Teams in Grafana anzeigen.
  • Nutzer auflisten: Alle Nutzer einer Organisation in Grafana anzeigen.
  • Alle Rollen auflisten: Alle Grafana-Rollen auflisten, optional gefiltert nach delegierbaren Rollen.
  • Rollendetails abrufen: Details zu einer bestimmten Grafana-Rolle anhand ihrer UID abrufen.
  • Zuweisungen für eine Rolle auflisten: Alle Nutzer, Teams und Servicekonten auflisten, denen eine Rolle zugewiesen ist.
  • Rollen für Nutzer auflisten: Alle Rollen auflisten, die einem oder mehreren Nutzern zugewiesen sind.
  • Rollen für Teams auflisten: Alle Rollen auflisten, die einem oder mehreren Teams zugewiesen sind.
  • Berechtigungen für eine Ressource auflisten: Alle für eine bestimmte Ressource (Dashboard, Datenquelle, Ordner usw.) definierten Berechtigungen auflisten.
  • Eine Grafana-Ressource beschreiben: Verfügbare Berechtigungen und Zuweisungsmöglichkeiten für einen Ressourcentyp auflisten.

User

  • Nutzerinformationen: Die aktuelle Grafana-Identität abrufen – Login, E-Mail-Adresse, Name, ob es sich um einen Grafana-Administrator (Server) handelt, die aktuelle Organisation und die Organisationen, auf die die Anmeldedaten zugreifen können (mit Rollen). Damit lassen sich gültige Werte für orgId bei Anfragen mit mehreren Organisationen ermitteln.

Navigation

  • Deeplinks generieren: Präzise Deeplink-URLs für Grafana-Ressourcen erstellen, statt sich auf URL-Schätzungen durch ein LLM zu verlassen.
    • Dashboard-Links: Direkte Links zu Dashboards anhand ihrer UID erstellen (z. B. http://localhost:3000/d/dashboard-uid)
    • Panel-Links: Links zu bestimmten Panels in Dashboards mit dem Parameter viewPanel erstellen (z. B. http://localhost:3000/d/dashboard-uid?viewPanel=5)
    • Explore-Links: Links zu Grafana Explore mit vorkonfigurierten Datenquellen erstellen (z. B. http://localhost:3000/explore?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}). Grafana-Versionen vor 10.2 verstehen panes nicht; für diese Versionen wird stattdessen das ältere Format ?left={...} ausgegeben.
    • Unterstützung für Zeitbereiche: Zeitbereichsparameter zu Links hinzufügen (from=now-1h&to=now)
    • Benutzerdefinierte Parameter: Zusätzliche Abfrageparameter wie Dashboard-Variablen oder Aktualisierungsintervalle einfügen

Annotations

  • Annotations abrufen: Annotations mit Filtern abfragen. Unterstützt Zeitbereich, Dashboard-UID, Tags und Abgleichmodus.
  • Annotation erstellen: Eine neue Annotation auf einem Dashboard oder Panel erstellen.
  • Graphite-Annotation erstellen: Annotations im Graphite-Format erstellen (what, when, tags, data).
  • Annotation aktualisieren: Alle Felder einer vorhandenen Annotation ersetzen (vollständige Aktualisierung).
  • Annotation patchen: Nur bestimmte Felder einer Annotation aktualisieren (teilweise Aktualisierung).
  • Annotation löschen: Eine Annotation anhand ihrer ID dauerhaft löschen.
  • Annotation-Tags abrufen: Verfügbare Annotation-Tags mit optionaler Filterung auflisten.

Snapshots

  • Snapshots auflisten: Dashboard-Snapshots mit optionalen Abfrage- und Limitfiltern auflisten.
  • Snapshot abrufen: Snapshot-Metadaten und Dashboard-Payload anhand des Snapshot-Schlüssels abrufen.
  • Snapshot erstellen: Einen Dashboard-Snapshot aus einer vollständigen Dashboard-Payload erstellen, optional mit Ablaufzeit und externen Snapshot-Optionen.
  • Snapshot löschen: Einen Snapshot anhand seines Snapshot-Schlüssels löschen.

Rendering

  • Panel- oder Dashboard-Bild abrufen: Ein Grafana-Dashboard-Panel oder ein vollständiges Dashboard als PNG-Bild rendern. Das Bild wird als base64-codierte Daten zurückgegeben und kann in Berichten, Alerts oder Präsentationen verwendet werden. Standardmäßig werden für ein Panel 1000×750 CSS-Pixel oder für ein vollständiges Dashboard 1200×900 bei Skalierung 1 verwendet. Für Explore gilt standardmäßig 1000×1000 bei Skalierung 1. Die Abmessungen unterliegen den Viewport-Grenzen des Bild-Renderers. Unterstützt die Anpassung von Abmessungen, Zeitbereich, Design, Skalierung und Dashboard-Variablen. Unterstützt außerdem das Rendern noch nicht angewendeter Dashboards aus einem Provisioning-Repository-Branch (z. B. einer git-sync-PR-Vorschau) über den optionalen Parameter provisioningPreview.

Provisioning

  • Provisioning-Repositories auflisten: Die für diese Grafana-Instanz konfigurierten Provisioning-Repositories (z. B. git-sync-Quellen) auflisten. Für jedes Repository werden der Slug sowie Quell-URL, Branch, Pfad, Synchronisierungsstatus und Zustand zurückgegeben.
  • Provisioning-Datei validieren: Eine Datei aus einem Provisioning-Repository auf einem bestimmten Branch oder Commit probeweise anwenden. Gibt zurück, ob sie akzeptiert würde, welche Ressourcenaktion (Erstellen/Aktualisieren) ausgeführt würde, welcher Ressourcentyp betroffen wäre und welche strukturierten Validierungsfehler vorliegen – dieselbe Zulassungsprüfung, die Grafanas PR-Kommentarfunktion verwendet.

Die Liste der Tools ist konfigurierbar, sodass du auswählen kannst, welche Tools dem MCP-Client zur Verfügung stehen sollen. Das ist nützlich, wenn du bestimmte Funktionen nicht verwendest oder das Kontextfenster nicht zu stark beanspruchen möchtest. Um eine Toolkategorie zu deaktivieren, verwende beim Starten des Servers das Flag --disable-<category>. Um beispielsweise die OnCall-Tools zu deaktivieren, verwende --disable-oncall, oder um die Generierung von Navigations-Deeplinks zu deaktivieren, verwende --disable-navigation.

RBAC-Berechtigungen

Jedes Tool benötigt bestimmte RBAC-Berechtigungen, um ordnungsgemäß zu funktionieren. Stelle beim Erstellen eines Servicekontos für den MCP-Server sicher, dass es über die erforderlichen Berechtigungen für die geplanten Tools verfügt. Die aufgeführten Berechtigungen sind die mindestens erforderlichen Aktionen – je nach Anwendungsfall benötigst du möglicherweise auch passende Bereiche (z. B. datasources:*, dashboards:*, folders:*).

Tipp: Wenn du mit Grafana RBAC nicht vertraut bist oder eine schnellere und einfachere Einrichtung bevorzugst, statt viele detaillierte Bereiche zu konfigurieren, kannst du dem Servicekonto eine integrierte Rolle wie Editor zuweisen. Die Rolle Editor gewährt umfassenden Lese-/Schreibzugriff, mit dem die meisten MCP-Servervorgänge möglich sind. Sie ist weniger granular (und daher weniger restriktiv) als manuell angewendete Bereiche. Verwende sie daher nur, wenn Komfort wichtiger ist als strikt nach dem Prinzip der geringsten Berechtigung gewährter Zugriff.

Hinweis: OnCall- und andere pluginbasierte Tools werden durch Plugin-Aktionen wie grafana-irm-app.schedules:read autorisiert. Die grundlegende Viewer-Rolle umfasst die Leseaktionen, die Editor-Rolle die Schreibaktionen. Für Incident-Tools ist nur plugins.app:access erforderlich; IRM autorisiert Incident-Aktionen anhand der grundlegenden Rolle.

Aktionen im Format group/resource:verb, wie dashboard.grafana.app/dashboards:get, gelten nur für Zugriffstoken im Namen eines Nutzers. Für ein Servicekonto sind nur die übrigen aufgeführten Aktionen erforderlich.

Weitere Informationen zu Grafana RBAC findest du in der offiziellen Dokumentation.

RBAC-Bereiche

Scopes legen die spezifischen Ressourcen fest, für die Berechtigungen gelten. Jede Aktion erfordert die passende Kombination aus Berechtigung und Scope.

Gängige Scope-Muster:

  • Umfassender Zugriff: Verwenden Sie *-Platzhalter für organisationsweiten Zugriff

    • datasources:* – Zugriff auf alle Datenquellen
    • dashboards:* – Zugriff auf alle Dashboards
    • folders:* – Zugriff auf alle Ordner
    • teams:* – Zugriff auf alle Teams
  • Eingeschränkter Zugriff: Verwenden Sie bestimmte UIDs oder IDs, um den Zugriff auf einzelne Ressourcen zu beschränken

    • datasources:uid:prometheus-uid – Zugriff nur auf eine bestimmte Prometheus-Datenquelle
    • dashboards:uid:abc123 – Zugriff nur auf das Dashboard mit der UID abc123
    • folders:uid:xyz789 – Zugriff nur auf den Ordner mit der UID xyz789
    • teams:id:5 – Zugriff nur auf das Team mit der ID 5
    • global.users:id:123 – Zugriff nur auf den Benutzer mit der ID 123

Beispiele:

  • Vollständiger Zugriff auf den MCP-Server: Gewähren Sie umfassende Berechtigungen für alle Tools

    datasources:* (datasources:read, datasources:query)
    dashboards:* (dashboards:read, dashboards:create, dashboards:write)
    folders:* (for dashboard creation and alert rules)
    teams:* (teams:read)
    global.users:* (users:read)
    
  • Eingeschränkter Zugriff auf Datenquellen: Fragen Sie nur bestimmte Prometheus- und Loki-Instanzen ab

    datasources:uid:prometheus-prod (datasources:query)
    datasources:uid:loki-prod (datasources:query)
    
  • Dashboard-spezifischer Zugriff: Lesen Sie nur bestimmte Dashboards

    dashboards:uid:monitoring-dashboard (dashboards:read)
    dashboards:uid:alerts-dashboard (dashboards:read)
    

Tools

ToolKategorieBeschreibungErforderliche RBAC-BerechtigungenErforderliche Scopes
list_teamsAdmin*Alle Teams auflistenteams:readteams:* oder teams:id:1
list_users_by_orgAdmin*Benutzer in einer Organisation mit Suche und Paginierung auflistenorg.users:readglobal.users:* oder global.users:id:123
list_all_rolesAdmin*Alle Grafana-Rollen auflistenroles:readroles:*
get_role_detailsAdmin*Details zu einer Grafana-Rolle abrufenroles:readroles:uid:editor
get_role_assignmentsAdmin*Zuweisungen für eine Rolle auflistenroles:read, teams.roles:read, users.roles:readroles:uid:editor
list_user_rolesAdmin*Rollen für Benutzer auflistenusers.roles:readglobal.users:id:123
list_team_rolesAdmin*Rollen für Teams auflistenteams.roles:readteams:id:7
get_resource_permissionsAdmin*Berechtigungen für eine Ressource auflistendashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:readdashboards:uid:abcd1234
get_resource_descriptionAdmin*Einen Grafana-Ressourcentyp beschreibendashboards.permissions:read, datasources.permissions:read, folders.permissions:read, serviceaccounts.permissions:read, teams.permissions:read, users.permissions:readdashboards:*
user_infoBenutzerAktuelle Identität, Funktionen und zugängliche OrganisationenKeine—
search_dashboardsSucheDashboards nach Abfrage, Ordner-UID, Ordnerpfad, Tag oder Markierung als Favorit suchendashboards:read, folders:readdashboards:* oder dashboards:uid:abc123
search_foldersSucheOrdner nach Titel suchenfolders:readfolders:* oder folders:uid:xyz789
get_dashboard_by_uidDashboardEin Dashboard anhand seiner UID abrufen, optional eine gespeicherte Versiondashboard.grafana.app/dashboards:get, dashboards:read, dashboards:writedashboards:uid:abc123
list_dashboard_versionsDashboardGespeicherte Versionen eines Dashboards auflisten (Version, Autor, Zeit, Nachricht)dashboards:read, dashboards:writedashboards:uid:abc123
update_dashboardDashboardEin Dashboard aktualisieren oder neu erstellendashboard.grafana.app/dashboards:create, dashboard.grafana.app/dashboards:get, dashboard.grafana.app/dashboards:update, dashboards:create, dashboards:read, dashboards:write, folders:readdashboards:*, folders:* oder folders:uid:xyz789
get_dashboard_panel_queriesDashboardPaneltitel, Abfragen, Datenquellen-UID und -Typ aus einem Dashboard abrufendashboard.grafana.app/dashboards:get, dashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*Eine oder mehrere Dashboard-Panel-Abfragen ausführendashboard.grafana.app/dashboards:get, dashboards:read, datasources:query, datasources:readdashboards:uid:*, datasources:uid:*
get_dashboard_propertyDashboardBestimmte Teile eines Dashboards mithilfe von JSONPath-Ausdrücken extrahierendashboard.grafana.app/dashboards:get, dashboards:readdashboards:uid:abc123
get_dashboard_summaryDashboardEine kompakte Zusammenfassung eines Dashboards ohne vollständiges JSON abrufendashboard.grafana.app/dashboards:get, dashboards:readdashboards:uid:abc123
create_folderDashboardEinen Ordner erstellenfolders:create, folders:read, folders:writefolders:*
list_datasourcesDatasourcesDatenquellen auflistendatasources:readdatasources:*
get_datasourceDatasourcesEine Datenquelle anhand der UID oder des Namens abrufendatasources:readdatasources:uid:prometheus-uid
check_datasources_healthDatasourcesDen Zustand einer oder mehrerer Datenquellen prüfendatasources:query, datasources:readdatasources:uid:*
create_datasourceDatasourcesEine Datenquelle erstellendatasources:create, datasources:readdatasources:*
update_datasourceDatasourcesEine Datenquelle aktualisierendatasources:read, datasources:writedatasources:* or datasources:uid:abc123
get_query_examplesExamples*Beispielabfragen für einen Datenquellentyp abrufenNonedatasources:*
query_prometheusPrometheusMetriken mit PromQL abfragen, ohne ein Diagramm zu öffnendatasources:query, datasources:readdatasources:uid:prometheus-uid
render_grafana_appRenderingEin aktiviertes Abfragetool ausführen und das Ergebnis in der interaktiven Grafana App anzeigendatasources:query, datasources:readdatasources:* or datasources:uid:<uid>
list_prometheus_metric_metadataPrometheusMetrikmetadaten auflistendatasources:query, datasources:readdatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusVerfügbare Metriknamen auflistendatasources:query, datasources:readdatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusLabelnamen auflisten, die einem Selektor entsprechendatasources:query, datasources:readdatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusWerte für ein bestimmtes Label auflistendatasources:query, datasources:readdatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusHistogramm-Perzentilwerte berechnendatasources:query, datasources:readdatasources:uid:prometheus-uid
list_incidentsIncidentVorfälle in Grafana Incident auflisten, optional mit ihren benutzerdefinierten Feldwertenplugins.app:accessN/A
create_incidentIncidentEinen Vorfall in Grafana Incident erstellen, optional mit benutzerdefinierten Feldernplugins.app:accessN/A
add_activity_to_incidentIncidentEin Aktivitätselement zu einem Vorfall in Grafana Incident hinzufügenplugins.app:accessN/A
update_incidentIncidentEinen Vorfall in Grafana Incident aktualisieren (Status, Schweregrad, Titel oder benutzerdefinierte Felder)plugins.app:accessN/A
get_incidentIncidentEinen einzelnen Vorfall anhand der ID abrufen, einschließlich seiner benutzerdefinierten Felderplugins.app:accessN/A
list_incident_custom_fieldsIncidentDie für Vorfälle konfigurierten benutzerdefinierten Felder mit ihren Typen und Auswahloptionen auflistenplugins.app:accessN/A
query_loki_logsLokiProtokolle mit LogQL abfragen und abrufen (entweder Protokoll- oder Metrikabfragen)datasources:query, datasources:readdatasources:uid:loki-uid
list_loki_label_namesLokiAlle verfügbaren Labelnamen in Logs auflistendatasources:query, datasources:readdatasources:uid:loki-uid
list_loki_label_valuesLokiWerte für ein bestimmtes Log-Label auflistendatasources:query, datasources:readdatasources:uid:loki-uid
query_loki_statsLokiStatistiken zu Log-Streams abrufendatasources:query, datasources:readdatasources:uid:loki-uid
query_loki_patternsLokiErkannte Log-Muster abfragen, um häufige Strukturen zu identifizierendatasources:query, datasources:readdatasources:uid:loki-uid
analyze_loki_labelsLokiEine Loki-Labelstrategie prüfen (live oder statisch) und optional die Abfrageleistung diagnostizierendatasources:query, datasources:readdatasources:uid:loki-uid
suggest_loki_alloy_label_configConfigEin Alloy-loki.process-Snippet generieren, das genehmigte Labels erzwingtNoneN/A
query_influxdbInfluxDB*InfluxDB mit InfluxQL (v1) oder Flux (v2) abfragendatasources:query, datasources:readdatasources:uid:influxdb-uid
list_sql_databasesSQL*Datenbanken, Schemas oder Kataloge aus einer SQL-Datenquelle auflistendatasources:query, datasources:readdatasources:uid:*
list_sql_tablesSQL*Tabellen in einer SQL-Datenquelle auflistendatasources:query, datasources:readdatasources:uid:*
describe_sql_tableSQL*Spaltenschema für eine Tabelle abrufendatasources:query, datasources:readdatasources:uid:*
query_sqlSQL*SQL-Abfragen mit Makrosubstitution ausführendatasources:query, datasources:readdatasources:uid:*
list_cloudwatch_namespacesCloudWatch*Verfügbare AWS-CloudWatch-Namespaces auflistendatasources:query, datasources:readdatasources:uid:*
list_cloudwatch_metricsCloudWatch*Metriken in einem Namespace auflistendatasources:query, datasources:readdatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*Dimensionen für eine Metrik auflistendatasources:query, datasources:readdatasources:uid:*
list_cloudwatch_dimension_valuesCloudWatch*Werte für einen Dimensionsschlüssel auflistendatasources:query, datasources:readdatasources:uid:*
query_cloudwatchCloudWatch*CloudWatch-Metrikabfragen ausführendatasources:query, datasources:readdatasources:uid:*
list_cloudwatch_log_groupsCloudWatch*CloudWatch-Loggruppen auflistendatasources:query, datasources:readdatasources:uid:*
list_cloudwatch_log_group_fieldsCloudWatch*In einer Loggruppe erkannte Felder auflistendatasources:query, datasources:readdatasources:uid:*
query_cloudwatch_logsCloudWatch*CloudWatch-Logs-Insights-Abfragen ausführendatasources:query, datasources:readdatasources:uid:*
list_cloud_logging_projectsCloud Logging*GCP-Projekte auflisten, auf die eine Google-Cloud-Logging-Datenquelle zugreifen kanndatasources:query, datasources:readdatasources:uid:*
list_cloud_logging_bucketsCloud Logging*Log-Buckets in einem GCP-Projekt auflistendatasources:query, datasources:readdatasources:uid:*
list_cloud_logging_viewsCloud Logging*Logansichten in einem Log-Bucket auflistendatasources:query, datasources:readdatasources:uid:*
query_cloud_loggingCloud Logging*Logs mit der Abfragesprache von Cloud Logging abfragendatasources:query, datasources:readdatasources:uid:*
query_azure_log_analyticsAzure Monitor*Azure Log Analytics-Arbeitsbereiche mit KQL abfragendatasources:query, datasources:readdatasources:uid:*
query_azure_resource_graphAzure Monitor*Azure Resource Graph mit KQL abfragendatasources:query, datasources:readdatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*Elasticsearch oder OpenSearch mit Lucene-Syntax oder Query DSL abfragendatasources:query, datasources:readdatasources:uid:datasource-uid
query_quickwitQuickwit*Quickwit mit Lucene-Syntax oder Query DSL abfragendatasources:query, datasources:readdatasources:uid:quickwit-uid
alerting_rules_readAlertingAlarmierungsregeln auflisten und prüfen (auflisten, abrufen, Versionen)alert.rules.external:read, alert.rules:read, datasources:read, folders:readfolders:* oder folders:uid:alerts-folder
alerting_rules_writeAlertingVon Grafana verwaltete Regeln erstellen, aktualisieren und löschen oder explizit datenquellenverwaltete Regeln erstellenalert.provisioning.provenance:write, alert.rules.external:read, alert.rules.external:write, alert.rules:create, alert.rules:delete, alert.rules:read, alert.rules:write, datasources:read, folders:readfolders:*, oder datasources:uid:<uid> für externe Erstellung
alerting_manage_routingAlertingBenachrichtigungsrichtlinien, Kontaktpunkte und Zeitintervalle verwaltenalert.notifications.external:read, alert.notifications.receivers:read, alert.notifications.routes:read, alert.notifications.time-intervals:read, alert.notifications:read, datasources:query, datasources:read, notifications.alerting.grafana.app/routingtrees:getGlobaler Geltungsbereich
alerting_routing_writeAlertingStandardmäßig von Grafana verwaltete Kontaktpunkte erstellen oder explizit externe Alertmanager-Empfänger erstellenalert.notifications.external:read, alert.notifications.external:write, alert.notifications.receivers:create, alert.provisioning.provenance:write, datasources:readGlobal oder datasources:uid:<uid> für externe Erstellung
alerting_silences_readAlertingAlarmierungsstummschaltungen auflisten und prüfen (auflisten, abrufen)alert.instances:read, alert.silences:readGlobaler Geltungsbereich
alerting_silences_writeAlertingAlarmierungsstummschaltungen erstellen, aktualisieren und ablaufen lassenalert.instances:create, alert.instances:read, alert.instances:write, alert.silences:create, alert.silences:read, alert.silences:writeGlobaler Geltungsbereich
list_oncall_schedulesOnCallZeitpläne aus Grafana OnCall auflistengrafana-irm-app.schedules:read, plugins.app:accessPlugin-spezifische Bereiche
get_oncall_shiftOnCallDetails zu einer bestimmten OnCall-Schicht abrufengrafana-irm-app.schedules:read, plugins.app:accessPlugin-spezifische Bereiche
get_current_oncall_usersOnCallAktuell für einen bestimmten Zeitplan eingeteilte Bereitschaftsnutzer abrufengrafana-irm-app.schedules:read, grafana-irm-app.user-settings:read, plugins.app:accessPlugin-spezifische Bereiche
list_oncall_teamsOnCallTeams aus Grafana OnCall auflistengrafana-irm-app.user-settings:read, plugins.app:accessPlugin-spezifische Bereiche
list_oncall_usersOnCallNutzer aus Grafana OnCall auflistengrafana-irm-app.user-settings:read, plugins.app:accessPlugin-spezifische Bereiche
list_alert_groupsOnCallAlarmgruppen aus Grafana OnCall mit Filteroptionen auflistengrafana-irm-app.alert-groups:read, plugins.app:accessPlugin-spezifische Bereiche
get_alert_groupOnCallEine bestimmte Alarmgruppe aus Grafana OnCall anhand ihrer ID abrufengrafana-irm-app.alert-groups:read, plugins.app:accessPlugin-spezifische Bereiche
update_alert_groupOnCallEine Alarmgruppe bestätigen, Bestätigung aufheben, auflösen oder Auflösung rückgängig machengrafana-irm-app.alert-groups:read, grafana-irm-app.alert-groups:write, plugins.app:accessPlugin-spezifische Bereiche
list_pyroscope_label_namesPyroscopeLabelnamen auflisten, die einem Selektor entsprechendatasources:query, datasources:readdatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeLabelwerte auflisten, die für einen Labelnamen einem Selektor entsprechendatasources:query, datasources:readdatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeVerfügbare Profiltypen auflistendatasources:query, datasources:readdatasources:uid:pyroscope-uid
query_pyroscopePyroscopeProfile, Metriken oder beides von Pyroscope abfragendatasources:query, datasources:readdatasources:uid:pyroscope-uid
get_assertionsAssertsZusammenfassung der Assertions für eine bestimmte Entität abrufenplugins.app:accessPlugin-spezifische Bereiche
agento11y_manage_conversationsAgent Observability*LLM-Konversationen aus Grafana Agent Observability auflisten, durchsuchen und abrufengrafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:accessN/A
agento11y_manage_generationsAgent Observability*Details zu LLM-Generierungen und Evaluierungsbewertungen aus Grafana Agent Observability abrufengrafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:accessN/A
agento11y_manage_agentsAgent Observability*Agentenkatalog lesen: Agents auflisten, eine Agent-Version vollständig abrufen, Versionsverlauf auflisten und Bewertungsaggregate pro Version abrufengrafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:accessN/A
agento11y_manage_evaluatorsAgent Observability*Evaluatoren, Evaluator-Vorlagen und den Judge-Katalog verwalten (auflisten, abrufen, upsert, forken, testen, löschen)grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; bei aktivierten Schreibvorgängen auch grafana-agento11y-app.eval:writeN/A
agento11y_manage_eval_rulesAgent Observability*Eval-Regeln und Guards verwalten (auflisten, abrufen, erstellen, aktualisieren, Vorschau anzeigen, löschen)grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; bei aktivierten Schreibvorgängen auch grafana-agento11y-app.eval:writeN/A
agento11y_manage_eval_collectionsAgent Observability*Gespeicherte Konversationen und die Sammlungen, in denen sie gruppiert sind, verwalten (auflisten, abrufen, speichern, erstellen, aktualisieren, löschen, Mitglieder hinzufügen und entfernen)grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; bei aktivierten Schreibvorgängen auch grafana-agento11y-app.eval:writeN/A
agento11y_manage_experimentsAgent Observability*Offline-Experimente, ihre Trials, Bewertungen, Artefaktmetadaten und Filterfacetten lesen; ein Experiment aktualisieren und abbrechengrafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; bei aktivierten Schreibvorgängen auch grafana-agento11y-app.eval:writeN/A
agento11y_manage_test_suitesAgent Observability*Die Testsuiten verwalten, mit denen Offline-Experimente ausgeführt werden, sowie deren Versionen und Testfälle (auflisten, abrufen, erstellen, aktualisieren, als Entwurf speichern, veröffentlichen, upsert, löschen)grafana-agento11y-app.conversations:read, grafana-agento11y-app.data:read, plugins.app:access; bei aktivierten Schreibvorgängen auch grafana-agento11y-app.eval:writeN/A
ask_assistantAssistant*Einen Prompt an Grafana Assistant senden und die vollständige Textantwort zurückgeben (mehrere Gesprächsrunden über contextId)grafana-assistant-app.chats:access, plugins.app:accessPlugin-spezifische Bereiche
generate_deeplinkNavigationPräzise Deeplink-URLs für Grafana-Ressourcen generierenNoneN/A
get_annotationsAnnotationsAnmerkungen mit Filtern abrufenannotations:readannotations:* oder annotations:id:123
create_annotationAnnotationsEine neue Anmerkung erstellen (Standard- oder Graphite-Format)annotations:createannotations:*
update_annotationAnnotationsBestimmte Felder einer Anmerkung aktualisieren (Teilaktualisierung)annotations:read, annotations:writeannotations:*
delete_annotationAnnotationsEine Anmerkung anhand ihrer ID löschenannotations:deleteannotations:*
get_annotation_tagsAnnotationsAnmerkungs-Tags mit optionaler Filterung auflistenannotations:readannotations:*
list_snapshotsSnapshotDashboard-Snapshots mit optionalen Abfrage- und Limitfiltern auflistensnapshots:readN/A
get_snapshotSnapshotSnapshot-Metadaten und Dashboard-Payload anhand des Snapshot-Schlüssels abrufenNoneN/A
create_snapshotSnapshotEinen Dashboard-Snapshot aus einer vollständigen Dashboard-Payload erstellendashboards:read, snapshots:createdashboards:uid:abc123
delete_snapshotSnapshotEinen Dashboard-Snapshot anhand des Snapshot-Schlüssels löschendashboards:write, snapshots:deletedashboards:uid:abc123
get_panel_imageRenderingEin gespeichertes Dashboard oder Panel, eine Bereitstellungsvorschau oder eine Ad-hoc-Explore-Ansicht als PNG-Bild renderndashboards:read, datasources:explore, datasources:query, datasources:read, provisioning.repositories:readdashboards:uid:abc123
list_provisioning_repositoriesProvisioningBereitstellungs-Repositories (z. B. git-sync-Quellen) mit Quell-URL, Branch, Synchronisierungsstatus und Zustand auflistenprovisioning.grafana.app/repositories:list, provisioning.repositories:readN/A
validate_provisioning_fileProvisioningEine Datei aus einem Bereitstellungs-Repository im Dry-Run-Modus anwenden und Validierungsfehler bei der Zulassung meldendashboard.grafana.app/dashboards:get, dashboards:read, folder.grafana.app/folders:get, folders:read, provisioning.grafana.app/repositories:get, provisioning.repositories:readN/A
search_docsDocsIn der Grafana-Dokumentation suchen oder Produktgruppen auflisten (Abfrage weglassen, um Produkte aufzulisten)NoneN/A
get_docDocsEine Dokumentationsseite abrufen; outline_only für Überschriften oder section für einen begrenzten Abruf festlegenNoneN/A
search_tempo_tracesTempoTraces mit TraceQL suchendatasources:query, datasources:readdatasources:uid:tempo-uid
query_tempo_metricsTempoMetriken aus Traces mit TraceQL berechnendatasources:query, datasources:readdatasources:uid:tempo-uid
get_tempo_traceTempoEinen Trace anhand seiner ID abrufendatasources:query, datasources:readdatasources:uid:tempo-uid
diff_tempo_tracesTempoZwei Traces vergleichendatasources:query, datasources:readdatasources:uid:tempo-uid
list_tempo_attribute_namesTempoNamen von Span- und Ressourcenattributen auflistendatasources:query, datasources:readdatasources:uid:tempo-uid
list_tempo_attribute_valuesTempoWerte für ein Trace-Attribut auflistendatasources:query, datasources:readdatasources:uid:tempo-uid
get_tempo_traceql_docsTempoTraceQL-Dokumentation abrufenNoneN/A
query_graphiteGraphite*Graphite-Metriken abfragendatasources:query, datasources:readdatasources:uid:graphite-uid
query_graphite_densityGraphite*Graphite-Metrikdichte abfragendatasources:query, datasources:readdatasources:uid:graphite-uid
list_graphite_metricsGraphite*Graphite-Metriken auflistendatasources:query, datasources:readdatasources:uid:graphite-uid
list_graphite_tagsGraphite*Graphite-Tags auflistendatasources:query, datasources:readdatasources:uid:graphite-uid
get_pluginPluginsEin installiertes Plugin abrufenplugins.app:accessN/A
search_plugin_informationPluginsIm Plugin-Katalog auf grafana.com suchenNoneN/A
install_pluginPluginsEin Plugin installierenplugins:installN/A
grafana_api_requestAPIEinen Grafana-HTTP-API-Endpunkt aufrufenNoneAbhängig vom Endpunkt
* Standardmäßig deaktiviert. Füge die Kategorie zu --enabled-tools hinzu, um sie zu aktivieren.

Das Tool render_grafana_app zeigt Metriken und Traces in kompatiblen MCP-Hosts an, wenn das Rendering und die entsprechenden Abfragekategorien aktiviert sind. Quellabfragetools geben Text und strukturierte Daten zur Analyse zurück. Informationen zur Einrichtung und Einbettung der Bibliothek findest du unter MCP Apps.

Referenz der CLI-Flags

Die Binärdatei mcp-grafana unterstützt verschiedene Befehlszeilen-Flags zur Konfiguration:

Transportoptionen:

  • -t, --transport: Transporttyp (stdio, sse oder streamable-http) – Standard: stdio
  • --address: Host und Port für den SSE-/streamable-http-Server – Standard: localhost:8000
  • --base-path: Basispfad für den SSE-/streamable-http-Server. /healthz und /metrics werden immer am Server-Root bereitgestellt, nicht unter diesem Präfix – es handelt sich um ausschließlich interne Endpunkte für Probes und Scraper. Wenn sie außerhalb des Anwendungspfads liegen, lässt sich die API leichter über einen Reverse-Proxy bereitstellen, ohne diese Endpunkte ebenfalls offenzulegen.
  • --endpoint-path: Endpunktpfad für den streamable-http-Server, angehängt an --base-path – Standard: /mcp
  • --sse-keepalive: Intervall zwischen Ping-Anfragen an jeden SSE-Client, damit Reverse-Proxys und Load-Balancer einen inaktiven Event-Stream nicht schließen (wodurch die Sitzung beendet würde). Lege den Wert unterhalb des Inaktivitäts-Timeouts des Proxys fest, z. B. 30s hinter dem standardmäßigen 60-s-proxy-read-timeout von ingress-nginx. Ein Client wird getrennt, wenn 3 Pings hintereinander jeweils eine halbe Intervalllänge lang unbeantwortet bleiben. Akzeptiert Go-Dauerzeichenfolgen, Minimum 1s – Standard: 0 (deaktiviert). Gilt nur für --transport sse
  • --server-name: Servername, der beim MCP-Handshake und in OTel service.name verwendet wird – Standard: mcp-grafana. Überschreibt die Umgebungsvariable GRAFANA_MCP_SERVER_NAME
  • --instructions-append: Text, der an die Serveranweisungen angehängt wird, die MCP-Clients bei der Initialisierung erhalten, sodass jeder verbundene Agent ihn sieht

Wenn --address den Port 0 verwendet, weist das Betriebssystem einen freien Port zu und der Server schreibt die gebundene Adresse atomar in mcp-grafana-address in seinem Arbeitsverzeichnis. Die Datei wird mit dem Modus 0600 erstellt.

[!NOTE] Bei SSE werden Header pro Anfrage nicht an Tool-Aufrufe weitergegeben: X-Grafana-Service-Account-Token / X-Grafana-API-Key, X-Grafana-Org-Id und in GRAFANA_FORWARD_HEADERS aufgeführte Header haben keine Wirkung. Tool-Aufrufe verwenden die Umgebungsanmeldedaten des Servers, und Überschreibungen von X-Grafana-URL funktionieren nicht. Verwende streamable-http, wenn jeder Aufrufer eine eigene Grafana-URL, eigene Anmeldedaten oder eine eigene Organisation benötigt.

HTTP-Transportsicherheit (nur SSE / streamable-http):

Die Validierung von Host/Origin wird auf jeder Route des MCP-Listeners erzwungen – /sse, /mcp und /healthz / /metrics, wenn sie denselben Listener verwenden –, damit ein Browser mit DNS-Rebinding keine dieser Routen erreichen kann. Der Stdio-Transport ist davon nicht betroffen. --healthz-address und --metrics-address starten einen separaten Listener, der nicht umschlossen ist.

  • --allowed-hosts: Durch Kommas getrennte Zulassungsliste mit Werten des Headers Host. Standardmäßig sind Loopback-Varianten von --address zugelassen (z. B. localhost:8000,127.0.0.1:8000,[::1]:8000). Ein Wert, der als leer geparst wird (nicht gesetzt, ,, , usw.), führt ebenfalls zu den Standardwerten, damit ein Tippfehler die Prüfung nicht unbemerkt deaktiviert. Anfragen mit einem Host-Header außerhalb der Zulassungsliste werden mit 403 abgelehnt. Übergib *, um die Validierung von Host zu deaktivieren – nur sicher, wenn ein vertrauenswürdiger Reverse-Proxy Host validiert. Für K8s-httpGet-Probes und externe /metrics-Scrapes ist entweder ein expliziter Hostname in dieser Liste, *, eine tcpSocket-Probe oder ein separater Port (--healthz-address / --metrics-address) erforderlich.
  • --allowed-origins: Durch Kommas getrennte Zulassungsliste mit Werten des Headers Origin. Standardmäßig leer – jede Anfrage mit einem Origin-Header wird abgelehnt (Browser senden bei Cross-Origin-Anfragen immer einen solchen Header, und kein Browser sollte diesen Server direkt aufrufen). Lege eine explizite Liste fest, um browserbasierte Clients zuzulassen, oder verwende *, um die Prüfung zu deaktivieren.
  • --allow-grafana-url-override: Auswahl von X-Grafana-URL aktivieren. Fällt auf GRAFANA_ALLOW_URL_OVERRIDE zurück; standardmäßig deaktiviert. Ohne Zulassungsliste können Aufrufer jede HTTP(S)-URL auswählen, die der Server erreichen kann.
  • --allowed-grafana-urls: Optionale, durch Kommas getrennte Zulassungsliste exakter Grafana-Basis-URLs für URL-Überschreibungen. Fällt auf GRAFANA_ALLOWED_URLS zurück. Erfordert --allow-grafana-url-override; ein explizit leeres Flag deaktiviert eine übernommene Liste.

Authentifizierung von Aufrufern (nur SSE / streamable-http):

Optional können MCP-Clients zur Authentifizierung beim Server verpflichtet werden. Dies ist unabhängig von den Anmeldedaten, mit denen der Server Grafana erreicht. Stdio ist davon nicht betroffen.

  • --server-auth-token: Bearer-Token, das Aufrufer als Authorization: Bearer <token> senden müssen. Fällt auf die Umgebungsvariable MCP_GRAFANA_SERVER_TOKEN zurück. Wenn gesetzt, werden Anfragen ohne gültiges Token mit 401 abgelehnt, bevor ein Tool ausgeführt wird. Verwende vorzugsweise die Umgebungsvariable, damit das Geheimnis nicht in den Prozessargumenten sichtbar ist.

Die Authentifizierung von Aufrufern wird nur erzwungen, wenn --server-auth-token gesetzt ist. Ist dies nicht der Fall und bindet der Server an eine Nicht-Loopback-Adresse, wird der Server gestartet, protokolliert aber einen Sicherheitsfehler – dieser wird auf der Protokollebene error ausgegeben, damit er nicht durch --log-level verborgen wird (Loopback und Stdio sind davon nicht betroffen). Eine zukünftige Hauptversion wird daraus einen Startfehler machen. Verwende TLS (oder TLS-Terminierung), wenn die Authentifizierung von Aufrufern an einer Nicht-Loopback-Adresse aktiviert ist. Wenn die Authentifizierung von Aufrufern aktiviert ist, wird der validierte Header Authorization entfernt, bevor Anfragen Grafana erreichen. Die Kombination von --server-auth-token mit GRAFANA_FORWARD_HEADERS=Authorization wird beim Start abgelehnt.

Grafana-URL-Überschreibungen (nur streamable-http):

[!WARNING] URL-Überschreibungen ermöglichen MCP-Aufrufern, ausgehende HTTP(S)-Ziele auszuwählen. Eine Zulassungsliste schränkt URLs ein, authentifiziert Aufrufer jedoch nicht und bindet Tokens nicht an Ziele.

Stelle den Server hinter einem authentifizierenden Proxy bereit, der jedes Ziel autorisiert, vom Client bereitgestellte URL- und Token-Header ersetzt und das passende Token bereitstellt. Beschränke den ausgehenden Netzwerkzugriff des Servers auf genehmigte Ziele.

Ohne Zulassungsliste kann ein gefälschtes Anfrage-Token Anfragen an jeden erreichbaren HTTP(S)-Dienst auslösen, einschließlich interner Dienste und Metadatendienste.

Setze GRAFANA_ALLOW_URL_OVERRIDE=true (oder --allow-grafana-url-override), um die Auswahl für eine große Flotte zu aktivieren. Um Ziele einzuschränken, setze zusätzlich GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana (oder --allowed-grafana-urls).

Sende diese Header bei jeder MCP-Anfrage, mit der ein Ziel ausgewählt wird:

X-Grafana-URL: https://one.example.com
X-Grafana-Service-Account-Token: <token for one.example.com>

Wenn --server-auth-token konfiguriert ist, sende auch Authorization: Bearer <MCP caller token>. Damit wird die Authentifizierung beim MCP-Server durchgeführt; dies ist unabhängig von X-Grafana-Service-Account-Token, das für die ausgewählte Grafana-Instanz bestimmt ist. Dein Proxy kann für jede Instanz ein anderes Grafana-Token senden; der Server verwendet kein einzelnes konfiguriertes Token für mehrere Instanzen. Der veraltete Header X-Grafana-API-Key funktioniert ebenfalls. Ein URL-Header ohne Grafana-Anfrage-Token wird abgelehnt. Verwende TLS für eingehende Anfragen, da sie Tokens enthalten.

Die Zulassungsliste vergleicht exakte Basis-URLs einschließlich Schema, Port und Pfad; Platzhalter werden nicht unterstützt. Die Grafana-Authentifizierung schützt nicht vor SSRF.

Für eine ausgewählte URL verwendet der Server weder GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, GRAFANA_API_KEY, die einfache Authentifizierung über Umgebungsvariablen, GRAFANA_EXTRA_HEADERS noch Clientzertifikate. Die TLS-Verifizierung bleibt auch dann aktiviert, wenn --tls-skip-verify gesetzt ist; eine konfigurierte CA-Datei wird weiterhin verwendet. Header, die ausdrücklich aus dieser Anfrage weitergeleitet werden, gelten weiterhin. Weiterleitungen und andere Grafana-API-Anfragen außerhalb der ausgewählten Basis-URL werden blockiert. Anfragen ohne X-Grafana-URL behalten das übliche Verhalten von GRAFANA_URL und der Umgebungsanmeldedaten bei. Diese Option gilt nur für streamable HTTP. Sie funktioniert nicht über SSE, da dort Header pro Anfrage nicht an Tool-Aufrufe weitergegeben werden. Eine dort ausgewählte URL wird daher ohne das Token des Aufrufers verwendet, sodass die Aufrufe fehlschlagen.

Debugging und Protokollierung:

  • --debug: Debug-Modus für detaillierte HTTP-Anfrage-/Antwortprotokollierung aktivieren
  • --log-level: Protokollebene (debug, info, warn, error) – Standard: info

Grafana-Clientoptionen:

  • --grafana-timeout: Zeitlimit für Anfragen des Grafana-Clients. Akzeptiert Go-Dauerzeichenfolgen (z. B. 10s, 500ms) – Standard: 30s
  • --allow-cross-origin-redirects: Grafana-Clients erlauben, Weiterleitungen zu einem anderen Schema, Host oder Port zu folgen. Standardmäßig false; GRAFANA_ALLOW_CROSS_ORIGIN_REDIRECTS ist der Fallback für die Umgebungsvariable. Dadurch können Grafana-Anmeldedaten an das Weiterleitungsziel gesendet werden. Für anfragebasierte Grafana-URLs bleibt das ausgewählte Ziel festgelegt.
  • --include-args-in-spans: Argumente von Tool-Aufrufen in OpenTelemetry-Spans aufnehmen. Nur in Nicht-Produktionsumgebungen oder dann aktivieren, wenn bekannt ist, dass die Argumente keine personenbezogenen Daten enthalten – Standard: false

Beobachtbarkeit:

  • --metrics: Prometheus-Metrikendpunkt unter /metrics aktivieren
  • --metrics-address: Separate Adresse für den Metrikserver (z. B. :9090). Wenn leer, werden Metriken auf dem Hauptserver bereitgestellt.
  • --healthz-address: Separate Adresse für /healthz (z. B. :8080). Wenn leer, wird /healthz auf dem Hauptserver bereitgestellt. Verwendet denselben Listener wie --metrics-address, wenn beide Adressen übereinstimmen. Zusätzliche Listener überspringen die Host-/Origin-Validierung.
  • --slow-request-threshold: Ein Ereignis protokollieren, wenn eine MCP-Anfrage (Tool-Aufruf, Auflistung, Ressourcenlesevorgang usw.) länger als diese Dauer dauert. Akzeptiert Go-Dauerzeichenfolgen (z. B. 500ms, 5s). Der Standardwert 0 deaktiviert die Protokollierung langsamer Anfragen. Siehe den Abschnitt Protokollierung langsamer Anfragen.
  • --slow-request-log-level: Protokollebene für Ereignisse langsamer Anfragen (info oder warn) – Standard: warn.

Anonyme Nutzungsstatistiken:

  • --usage-stats: Meldung anonymer Nutzungsstatistiken: enabled, disabled oder log (gibt den Bericht aus, der gesendet würde, und sendet nichts). Überschreibt die Umgebungsvariable GRAFANA_USAGE_STATS, die wiederum DO_NOT_TRACK überschreibt; jeder nicht erkannte Wert deaktiviert die Meldung. Siehe den Abschnitt Anonyme Nutzungsstatistiken. Tool-Konfiguration:

  • --enabled-tools: Durch Kommas getrennte Liste aktivierter Kategorien – Standard: alle Kategorien außer admin, agento11y, assistant, athena, azuremonitor, clickhouse, cloudlogging, cloudwatch, dsquery, elasticsearch, examples, graphite, quickwit, runpanelquery und snowflake. Um deaktivierte Kategorien zu aktivieren, füge sie der Liste hinzu (z. B. "search,datasource,...,snowflake")

  • --max-loki-log-limit: Maximale Anzahl zurückgegebener Logzeilen pro Aufruf von query_loki_logs – Standard: 100. Hinweis: Setze diesen Wert mindestens 1 unter Lokis serverseitigem max_entries_limit_per_query, damit eine Kürzung erkannt werden kann (das Tool fordert intern limit+1 an, um festzustellen, ob weitere Daten vorhanden sind).

  • --loki-guardrail-mode: Schutzgrenze für die Kosten von Loki-Abfragen für query_loki_logs – Standard: off. Loki erzwingt max_query_bytes_read bei Log-Abfragen ohne Zeilenfilter nicht. Daher kann ein breiter Selektor über einen großen Zeitraum Terabytes durchsuchen. Die Schutzgrenze erfordert einen selektiven Stream-Selektor, begrenzt den effektiven Zeitraum (einschließlich Range-Vector-Dauern wie [30d]) und prüft vor der Abfrage die Byte-Schätzung des Loki-Index bzw. der Statistiken. shadow protokolliert Abfragen, die blockiert würden, lässt sie aber laufen (der Roundtrip für Index und Statistiken fällt trotzdem an); enforce weist sie mit Hinweisen zur Umformulierung zurück, die das LLM umsetzen kann. Bei VictoriaLogs gilt die Schutzgrenze nur für Abfragen in Selektorform ({...}) – wenn kein Selektor geparst werden kann (die übliche LogsQL-Form ohne geschweifte Klammern), wird die Abfrage unverändert durchgereicht und die Prüfung des Byte-Budgets nie angewendet (keine kostengünstige Indexschätzung). Ersatz durch Umgebungsvariable: GRAFANA_LOKI_GUARDRAIL_MODE.

  • --loki-guardrail-max-bytes: Maximale Anzahl von Bytes, die ein einzelner Aufruf von query_loki_logs durchsuchen darf, geschätzt über Lokis Index-/Stats-API – Standard: 107374182400 (100 GiB). 0 deaktiviert die Prüfung des Byte-Budgets. Ersatz durch Umgebungsvariable: GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.

  • --loki-guardrail-max-range: Maximaler effektiver Zeitraum für einen einzelnen Aufruf von query_loki_logs, einschließlich Range-Vector-Dauern – Standard: 24h. Akzeptiert Go-Dauerzeichenfolgen. 0 deaktiviert die Bereichsprüfung. Ersatz durch Umgebungsvariable: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.

  • --prometheus-guardrail-mode: Schutzgrenze für Prometheus-Abfragen für query_prometheus, query_prometheus_histogram und die Prometheus-Abfragen von run_panel_query – Standard: off. Die Schutzgrenze beschränkt den effektiven Zeitraum einer Abfrage und die Anzahl der angeforderten Punkte pro Zeitreihe, bevor die Abfrage die Datenquelle erreicht. Eine unabhängige, optionale Selektorrichtlinie kann für jeden Vektor-Selektor eine nicht leere positive Label-Bedingung zusätzlich zum Metriknamen verlangen. Beispiele und Einschränkungen findest du unter Selektorrichtlinie. shadow protokolliert Abfragen, die blockiert würden, lässt sie aber laufen; enforce weist sie mit Hinweisen zur Umformulierung zurück, die das LLM umsetzen kann (run_panel_query meldet dies im Eintrag errors des Ergebnisses für das betreffende Panel). Ersatz durch Umgebungsvariable: GRAFANA_PROMETHEUS_GUARDRAIL_MODE.

  • --prometheus-guardrail-require-selective-labels: Verlangt, dass jeder Vektor-Selektor eine nicht leere positive Label-Bedingung zusätzlich zum Metriknamen enthält. Standard: false; unabhängig von den Budgets für Zeitraum und Punkte, auch wenn beide 0 sind. Gilt nur, wenn der Schutzgrenzenmodus nicht off ist. Ersatz durch Umgebungsvariable: GRAFANA_PROMETHEUS_GUARDRAIL_REQUIRE_SELECTIVE_LABELS. Explizite CLI-Werte, einschließlich false, haben Vorrang vor der Umgebung.

  • --prometheus-guardrail-max-range: Maximaler effektiver Zeitraum für eine einzelne PromQL-Abfrage – Standard: 192h. Der effektive Zeitraum umfasst den eigenen Zeitraum der Abfrage (bei Instant-Abfragen null) zuzüglich des längsten Range-Vector- oder Subquery-Fensters im Ausdruck. Verschachtelte Subquery-Bereiche werden addiert, sodass max_over_time(rate(x[5m])[30d:1m]) 30d5m ergibt. Akzeptiert Go-Dauerzeichenfolgen. Schreibe daher 192h und nicht 8d. 0 deaktiviert die Bereichsprüfung. Ersatz durch Umgebungsvariable: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_RANGE.

  • --prometheus-guardrail-max-points: Maximale Anzahl von Punkten pro Zeitreihe, die eine Bereichsabfrage anfordern darf, floor(range / step) + 1 – Standard: 11000, Prometheus' eigenes Limit pro Zeitreihe. Die Hinweise nennen den kleinsten passenden stepSeconds. 0 deaktiviert die Punkteprüfung. Ersatz durch Umgebungsvariable: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_POINTS.

  • --prometheus-guardrail-max-metric-cardinality: Optionale TSDB-Bereichsrichtlinie. Standard: 0 (deaktiviert). Für einen exakten Metriknamen, dessen gemeldete Anzahl von Zeitreihen über diesem Schwellenwert liegt, ist ein nicht leerer exakter Matcher für ein konfiguriertes Bereichslabel erforderlich. Nur aktiv, wenn der Modus nicht off ist. Ersatz durch Umgebungsvariable: GRAFANA_PROMETHEUS_GUARDRAIL_MAX_METRIC_CARDINALITY.

  • --prometheus-guardrail-cardinality-cache-ttl: Gültigkeitsdauer zwischengespeicherter TSDB-Snapshots. Standard: 10m; 0 verwendet ebenfalls 10m. Ersatz durch Umgebungsvariable: GRAFANA_PROMETHEUS_GUARDRAIL_CARDINALITY_CACHE_TTL.

  • --prometheus-guardrail-cardinality-scope-labels: Durch Kommas getrennte Labels, deren nicht leere exakte Matcher die Kardinalitätsrichtlinie erfüllen. Standard: job,instance,namespace,pod,service,cluster; bei leerem Wert werden diese Standards verwendet. __name__ ist nicht zulässig. Ersatz durch Umgebungsvariable: GRAFANA_PROMETHEUS_GUARDRAIL_CARDINALITY_SCOPE_LABELS. Explizite CLI-Einstellungen haben Vorrang vor den entsprechenden Umgebungsvariablen.

    Einschränkungen der Prometheus-Schutzgrenze: Die Punkteprüfung begrenzt die angeforderte Auflösung, nicht die Anzahl der Zeitreihen, Samples oder Subquery-Auswertungen. Außerdem kann Grafana den Bereich anpassen oder den Schritt vergrößern. Modifikatoren für offset und @ werden ignoriert. Grafana-Makros wie $__rate_interval und $__range werden vor der Messung des Ausdrucks mit den von Grafana verwendeten Werten ersetzt ($__rate_interval ist das Vierfache des Schritts). Ausdrücke, die die Schutzgrenze weiterhin nicht parsen kann (z. B. solche mit Dashboard-Variablen wie $window oder Syntax, die nur eine andere Dialektvariante akzeptiert), werden nur anhand des eigenen Zeitraums und Schritts der Abfrage geprüft und ansonsten ausgeführt. run_panel_query hat keinen Schrittparameter und vergrößert daher bei langen Zeiträumen seinen 1-Minuten-Schritt, um wie Grafana innerhalb von 11000 Punkten zu bleiben, oder innerhalb eines niedrigeren --prometheus-guardrail-max-points im Modus enforce.

  • --prometheus-enforced-matchers: PromQL-Label-Matcher, die mit AND in jede native Prometheus-Abfrage eingefügt werden, um einzuschränken, welche Zeitreihen gelesen werden können (z. B. environment=~"prod|staging"). Erfordert --disable-api. Siehe Durchsetzung von Prometheus-Abfragen.

  • --loki-enforced-matchers: LogQL-Label-Matcher, die mit AND in jede native Loki-Abfrage eingefügt werden, um einzuschränken, welche Log-Streams gelesen werden können (z. B. environment=~"prod|staging"). Erfordert --disable-api. Siehe Durchsetzung von Loki-Abfragen.

  • --loki-label-enumeration-fallback: Verhalten der Label-Aufzählungstools, wenn negative erzwungene Matcher sie nicht einschränken können: reject (Standard) oder unfiltered. Siehe Durchsetzung von Loki-Abfragen.

  • --dashboard-schema: Auf v2 setzen, damit update_dashboard einen klassischen v1-Body (panels[]) ablehnt, der ein neues Dashboard erstellen würde, wenn Grafana das Dashboard-Schema v2 bereitstellt. Der Fehler enthält einen minimalen v2-Body, der erneut verwendet werden kann. Vorhandene v1-Dashboards bleiben bearbeitbar; Grafana-Versionen ohne v2 sind nicht betroffen. Standard: leer (keine Änderung). Ersatz durch Umgebungsvariable: GRAFANA_DASHBOARD_SCHEMA.

  • --disable-search: Suchtools deaktivieren

  • --disable-datasource: Datenquellentools deaktivieren

  • --disable-incident: Incident-Tools deaktivieren

  • --disable-prometheus: Prometheus-Tools deaktivieren

  • --disable-write: Schreibtools deaktivieren (Erstellungs-/Aktualisierungsvorgänge)

  • --disable-query: Abfragetools deaktivieren (Tools, die eine Abfrage für eine Datenquelle ausführen); Metadaten- und Ermittlungstools bleiben verfügbar

  • --enable-query: Die Raw-SQL-Abfragetools (query_sql, query_influxdb) auch unter --disable-write registriert lassen und query_datasource, eine Quelle von render_grafana_app, verfügbar lassen. Für die Raw-SQL-Tools entspricht dies --enable-write-tools=query_sql,query_influxdb; als Kurzform für diesen häufigen Anwendungsfall beibehalten.

  • --enable-write-tools: Durch Kommas getrennte Liste einzelner Toolnamen, die auch unter --disable-write registriert bleiben sollen, wenn ihr Schreibverhalten ausreichend eingeschränkt ist, um sie unabhängig wieder zu aktivieren. Hat keine Wirkung auf ein Tool, dessen gesamte Kategorie deaktiviert ist. Beispielsweise lässt --enable-write-tools=generate_deeplink die URL-Kürzung (shorten=true) unter --disable-write weiterhin zu, und --enable-write-tools=alerting_rules_write ermöglicht Änderungen an Alarmierungsregeln, ohne andere Schreibtools zu aktivieren.

  • --disable-loki: Loki-Tools deaktivieren

  • --disable-elasticsearch: Elasticsearch- und OpenSearch-Tools deaktivieren

  • --disable-quickwit: Quickwit-Tools deaktivieren

  • --disable-influxdb: InfluxDB-Tools deaktivieren

  • --disable-alerting: Alarmierungstools deaktivieren

  • --disable-dashboard: Dashboard-Tools deaktivieren

  • --disable-oncall: OnCall-Tools deaktivieren

  • --disable-asserts: Asserts-Tools deaktivieren

  • --disable-admin: Admin-Tools deaktivieren

  • --disable-pyroscope: Pyroscope-Tools deaktivieren

  • --disable-navigation: Navigationstools deaktivieren

  • --disable-rendering: Rendering-Tools deaktivieren (Panel-/Dashboard-Bildexport)

  • --disable-snapshot: Snapshot-Tools deaktivieren

  • --disable-cloudwatch: CloudWatch-Tools deaktivieren

  • --disable-cloudlogging: Google-Cloud-Logging-Tools deaktivieren

  • --disable-azuremonitor: Azure-Monitor-Tools deaktivieren

  • --disable-examples: Abfragebeispiel-Tools deaktivieren

  • --disable-sql: SQL-Datenquellentools deaktivieren (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL, BigQuery). Die Aliase --disable-clickhouse, --disable-snowflake, --disable-athena funktionieren ebenfalls.

  • --disable-runpanelquery: Tools zum Ausführen von Panel-Abfragen deaktivieren

  • --disable-graphite: Graphite-Tools deaktivieren

  • --disable-dsquery: Die Quelle query_datasource von render_grafana_app deaktivieren

  • --disable-provisioning: Provisionierungstools deaktivieren

  • --disable-agento11y: Agent-Observability-Tools deaktivieren

  • --disable-assistant: Grafana-Assistant-Tools deaktivieren

  • --disable-docs: Dokumentationstools deaktivieren

Schreibgeschützter Modus

Das Flag --disable-write ermöglicht den Betrieb des MCP-Servers im schreibgeschützten Modus und verhindert so Schreibvorgänge in deiner Grafana-Instanz. Dies ist nützlich, wenn du einen sicheren, schreibgeschützten Zugriff bereitstellen möchtest, zum Beispiel für:

  • Dienstkonten mit eingeschränkten Leseberechtigungen
  • KI-Assistenten, die Observability-Daten ohne Änderungsmöglichkeiten erhalten sollen
  • Produktionsumgebungen, in denen der Schreibzugriff eingeschränkt werden soll
  • Test- und Entwicklungsszenarien, in denen versehentliche Änderungen verhindert werden sollen

Wenn --disable-write aktiviert ist, sind die folgenden Schreibvorgänge deaktiviert:

Dashboard-Tools:

  • update_dashboard

Ordner-Tools:

  • create_folder

Incident-Tools:

  • create_incident
  • add_activity_to_incident
  • update_incident

Alarmierungstools:

  • alerting_rules_write (Erstellungs-, Aktualisierungs- und Löschvorgänge)
  • alerting_silences_write (Erstellungs-, Aktualisierungs- und Löschvorgänge)
  • alerting_routing_write (Vorgang create_contact_point)

Jedes Alarmierungs-Schreibtool kann einzeln mit --enable-write-tools=<name> beibehalten werden.

OnCall-Tools:

  • update_alert_group

Annotations-Tools:

  • create_annotation
  • update_annotation
  • delete_annotation

Snapshot-Tools:

  • create_snapshot
  • delete_snapshot

Navigationstools:

  • generate_deeplink (shorten=true wird ignoriert und die vollständige URL zurückgegeben; übergib --enable-write-tools=generate_deeplink, um die URL-Kürzung beizubehalten)

Raw-SQL-Abfragetools:

Diese führen jede übergebene Abfrage aus, ohne sie zu prüfen. Daher können sie Schreibvorgänge ausführen, wenn die Anmeldedaten der Datenquelle dies erlauben – query_sql führt ein DROP TABLE aus, query_influxdb führt ein DELETE aus. Im schreibgeschützten Modus werden sie daher entfernt. Übergib --enable-query, um sie beizubehalten, wenn bekannt ist, dass die Anmeldedaten der Datenquelle schreibgeschützt sind.

  • query_sql
  • query_influxdb

Agent-Observability-Tools:

  • agento11y_manage_evaluators (Upsert-, Lösch-, Fork- und Evaluator-Testvorgänge)
  • agento11y_manage_eval_rules (Erstellungs-, Aktualisierungs-, Lösch-, Vorschau-Regel- und Schutzvorgänge)
  • agento11y_manage_eval_collections (gespeicherte Unterhaltungen speichern und löschen; Sammlungen erstellen, aktualisieren und löschen; Sammlungsmitglieder hinzufügen und entfernen)
  • agento11y_manage_experiments (Experimente aktualisieren und abbrechen)
  • agento11y_manage_test_suites (Testsuiten erstellen und aktualisieren; Versionen erstellen und veröffentlichen; Testfälle per Upsert hinzufügen und löschen) Alle Lesevorgänge bleiben verfügbar. So können Sie Dashboards abfragen, PromQL-/LogQL-Abfragen ausführen, Ressourcen auflisten und Daten abrufen. Abfragesprachen, die keine Schreibvorgänge ausdrücken können — PromQL, LogQL, TraceQL, die Elasticsearch DSL, Graphite und CloudWatch — behalten ihre Abfragetools im schreibgeschützten Modus; nur die oben aufgeführten Raw-SQL-Tools werden entfernt.

Abfragefreier Modus

Das Flag --disable-query entfernt alle Tools, die eine Abfrage an eine Datenquelle ausführen, während die Metadaten- und Ermittlungstools erhalten bleiben. Das ist nützlich, wenn ein Assistent erkunden können soll, was vorhanden ist — Datenquellen, Dashboards, Metriknamen, Labels und Tabellenschemas —, ohne potenziell kostspielige oder sensible Abfragen auszuführen, beispielsweise wenn das Dienstkonto über datasources:read, aber nicht über datasources:query verfügt.

Dies ist die restriktivste der drei Abfrageeinstellungen und hat Vorrang vor --enable-query:

FlagsSichere Abfragetools (query_prometheus, query_loki_logs, run_panel_query, …)Raw-SQL-Abfragetools (query_sql, query_influxdb)
(none)registriertregistriert
--disable-writeregistriertnicht registriert
--disable-write --enable-queryregistriertregistriert
--disable-querynicht registriertnicht registriert
--disable-query --enable-querynicht registriertnicht registriert

Wenn --disable-query aktiviert ist, werden die folgenden Tools nicht registriert:

Prometheus-Tools:

  • query_prometheus
  • query_prometheus_histogram

Rendering-Tools:

  • render_grafana_app

Loki-Tools:

  • query_loki_logs
  • query_loki_patterns

query_loki_stats und analyze_loki_labels bleiben registriert: Beide senden einen Selektor an die Datenquelle, lesen jedoch den Index und geben die Anzahl der Streams, Chunks und Bytes statt des Log-Inhalts zurück.

Elasticsearch-/OpenSearch- und Quickwit-Tools:

  • query_elasticsearch
  • query_quickwit

InfluxDB-Tools (werden auch durch --disable-write entfernt, siehe oben):

  • query_influxdb

SQL-Datenquellentools (werden auch durch --disable-write entfernt, siehe oben):

  • query_sql

Graphite-Tools:

  • query_graphite
  • query_graphite_density

CloudWatch-Tools:

  • query_cloudwatch
  • query_cloudwatch_logs

Google Cloud Logging-Tools:

  • query_cloud_logging

Azure Monitor-Tools:

  • query_azure_log_analytics
  • query_azure_resource_graph

Pyroscope-Tools:

  • query_pyroscope

Tools zum Ausführen von Panel-Abfragen:

  • run_panel_query

Die Kategorien elasticsearch, quickwit, influxdb, runpanelquery und azuremonitor enthalten keine weiteren Tools. Daher werden bei deaktivierten Abfragen überhaupt keine Tools aus diesen Kategorien registriert. Die zugehörigen Tools in allen anderen Kategorien — list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects usw. — bleiben verfügbar.

Beachten Sie, dass --disable-query die Abfragetools und den POST-Pfad zu grafana_api_request-/api/ds/query steuert, aber nicht jeden Zugriffspfad zu einer Datenquelle überwacht. Im schreibgeschützten Modus erlaubt grafana_api_request POST-Anfragen an /api/ds/query nur, wenn Abfragetools aktiviert sind (dieselbe Steuerung wie bei den Raw-SQL-Tools — durch --disable-write blockiert, sofern --enable-query sie nicht außer Kraft setzt). get_panel_image, das ein Panel serverseitig rendert, ist davon nicht betroffen.

Client-TLS-Konfiguration (für Grafana-Verbindungen):

  • --tls-cert-file: Pfad zur TLS-Zertifikatsdatei für die Clientauthentifizierung
  • --tls-key-file: Pfad zur privaten TLS-Schlüsseldatei für die Clientauthentifizierung
  • --tls-ca-file: Pfad zur TLS-CA-Zertifikatsdatei für die Serverüberprüfung
  • --tls-skip-verify: TLS-Zertifikatsüberprüfung überspringen (unsicher)

Server-TLS-Konfiguration (nur für den streamable-http-Transport):

  • --server.tls-cert-file: Pfad zur TLS-Zertifikatsdatei für HTTPS auf dem Server
  • --server.tls-key-file: Pfad zur privaten TLS-Schlüsseldatei für HTTPS auf dem Server

Verwendung

Dieser MCP-Server funktioniert sowohl mit lokalen Grafana-Instanzen als auch mit Grafana Cloud. Verwenden Sie für Grafana Cloud die URL Ihrer Instanz (z. B. https://myinstance.grafana.net) anstelle von http://localhost:3000 in den folgenden Konfigurationsbeispielen.

  1. Wenn Sie die Authentifizierung mit einem Dienstkontotoken verwenden, erstellen Sie in Grafana ein Dienstkonto mit ausreichenden Berechtigungen für die gewünschten Tools, generieren Sie ein Dienstkontotoken und kopieren Sie es zur Verwendung in der Konfigurationsdatei in die Zwischenablage. Einzelheiten zum Erstellen von Dienstkontotoken finden Sie in der Grafana-Dokumentation zu Dienstkonten. Tipp: Wenn Sie keine fein abgestuften RBAC-Bereiche konfigurieren möchten, können Sie dem Dienstkonto stattdessen die integrierte Rolle Editor zuweisen. Diese gewährt umfassenden Lese-/Schreibzugriff, der die meisten Vorgänge des MCP-Servers abdeckt. Verwenden Sie sie, wenn Komfort wichtiger ist als die strikte Einhaltung des Prinzips der geringsten Berechtigungen.

    Hinweis: Die Umgebungsvariable GRAFANA_API_KEY ist veraltet und wird in einer zukünftigen Version entfernt. Bitte wechseln Sie stattdessen zu GRAFANA_SERVICE_ACCOUNT_TOKEN. Der alte Variablenname funktioniert aus Gründen der Abwärtskompatibilität weiterhin, es werden jedoch Warnungen zur Veraltung angezeigt.

Dienstkontotoken aus einer Datei lesen

Anstatt das Token inline über GRAFANA_SERVICE_ACCOUNT_TOKEN zu übergeben, können Sie GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE auf einen Dateipfad mit dem Token verweisen lassen. Die Datei wird bei jeder Anfrage neu eingelesen, sodass rotierte Token automatisch übernommen werden, ohne den Server neu zu starten.

Das ist besonders in Kubernetes nützlich, wo ein als Volume eingebundenes Secret bei Änderungen am zugrunde liegenden Secret direkt aktualisiert wird (in der Regel innerhalb von etwa einer Minute). In Verbindung mit dem Client-Cache pro Anfrage — dessen Schlüsselwert das Token ist — führt ein rotiertes Token transparent zu einem neuen Client, ohne dass ein Pod-Neustart oder eine Ausfallzeit erforderlich ist:

env:
  - name: GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE
    value: /var/run/secrets/grafana/token
volumeMounts:
  - name: grafana-token
    mountPath: /var/run/secrets/grafana
    readOnly: true
volumes:
  - name: grafana-token
    secret:
      secretName: grafana-mcp-token

Umgebende Leerzeichen (einschließlich eines abschließenden Zeilenumbruchs) werden aus dem Dateiinhalt entfernt. Wenn sowohl GRAFANA_SERVICE_ACCOUNT_TOKEN als auch GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE gesetzt sind, hat das Inline-Token Vorrang.

Unterstützung mehrerer Organisationen

Sie können die Organisation, mit der interagiert werden soll, auf eine der folgenden Arten angeben:

  • Umgebungsvariable: Setzen Sie GRAFANA_ORG_ID auf die numerische Organisations-ID.
  • HTTP-Header: Setzen Sie X-Grafana-Org-Id, wenn Sie den streamable-HTTP-Transport verwenden (der Header hat Vorrang vor der Umgebungsvariable. So können Sie auch eine Standardorganisation festlegen).

Wenn eine Organisations-ID angegeben wird, setzt der MCP-Server bei allen Anfragen an Grafana den Header X-Grafana-Org-Id, damit Vorgänge im Kontext der angegebenen Organisation ausgeführt werden.

Dynamische Organisationsauswahl (pro Aufruf)

Mit den obigen Optionen wird die Organisation für die gesamte Verbindung festgelegt. Damit eine einzelne Verbindung bei jedem Toolaufruf unterschiedliche Organisationen ansprechen kann, starten Sie den Server mit dem Flag --dynamic-multi-org. Diese Option ist standardmäßig deaktiviert.

Wenn die Option aktiviert ist, akzeptiert jedes Tool ein optionales Argument orgId, das die Organisation der Verbindung für diesen Aufruf überschreibt (und sowohl den Header X-Grafana-Org-Id als auch bei App-Platform-APIs den aufgelösten Kubernetes-Namespace bestimmt). Proxied-Datenquellentools werden außerdem für alle Organisationen ermittelt, auf die die Anmeldedaten Zugriff haben. Bei Aufrufen ohne orgId wird die Standardorganisation der Verbindung verwendet.

Dies funktioniert nur mit Anmeldedaten, die zu mehreren Organisationen gehören (z. B. einem Benutzer oder einer Identität im Auftrag eines Benutzers); ein Dienstkontotoken bleibt an seine einzelne Organisation gebunden. Verwenden Sie das Tool user_info, um herauszufinden, welche orgId-Werte gültig sind.

Beispiel mit Organisations-ID:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        "GRAFANA_ORG_ID": "2"
      }
    }
  }
}

Benutzerdefinierte HTTP-Header

Mit der Umgebungsvariable GRAFANA_EXTRA_HEADERS können Sie beliebige HTTP-Header zu allen Grafana-API-Anfragen hinzufügen. Der Wert muss ein JSON-Objekt sein, das Headernamen den jeweiligen Werten zuordnet.

Beispiel mit benutzerdefinierten Headern:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_EXTRA_HEADERS": "{\"X-Custom-Header\": \"custom-value\", \"X-Tenant-ID\": \"tenant-123\"}"
      }
    }
  }
}

SOCKS5-Proxy

Mit der Umgebungsvariable GRAFANA_SOCKS5_PROXY können Sie alle Anfragen, die dieser Server an Grafana sendet, über einen SOCKS5-Proxy leiten. Der Proxy gilt nur für den Grafana-Datenverkehr dieses Servers: Die globalen Variablen HTTP_PROXY/HTTPS_PROXY werden nicht geändert. Ist die Variable gesetzt, überschreibt sie die Proxyauswahl für Grafana-Transporte, ohne andere MCP-Server oder Ihre Shell-Sitzung zu beeinflussen. Ist sie nicht gesetzt, bleibt das Verhalten unverändert.

Die URL muss das Schema socks5:// oder socks5h:// verwenden (Go behandelt beide identisch: Die Hostnamenauflösung wird an den Proxy delegiert) und kann Anmeldedaten enthalten, z. B. socks5://user:pass@127.0.0.1:1080.

Beispiel:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
        "GRAFANA_SOCKS5_PROXY": "socks5://127.0.0.1:1080"
      }
    }
  }
}

Eine ungültige Proxy-URL führt zu einem Startfehler. Wenn zur Laufzeit keine proxied Verbindung aufgebaut werden kann, bricht der Server sicher ab, anstatt Grafana-Datenverkehr stillschweigend direkt zu senden.

Header vom Client weiterleiten (nur Streamable-HTTP)

Wenn der MCP-Server hinter einem Gateway oder Reverse-Proxy läuft, das bzw. der SSO verarbeitet (z. B. ein AWS ALB mit OIDC), muss das Sitzungscookie jedes Benutzers Grafana erreichen, damit Grafana die Anfrage dem authentifizierten Benutzer zuordnen kann. Die Umgebungsvariable GRAFANA_FORWARD_HEADERS ermöglicht dies, indem sie eine durch Kommas getrennte Zulassungsliste von Headernamen angibt, die aus der eingehenden HTTP-Anfrage in jede ausgehende Grafana-API-Anfrage kopiert werden.

Dies gilt nur bei Verwendung des streamable-http-Transports (-t streamable-http). Im stdio- oder SSE-Modus hat die Variable keine Wirkung.

Beispiel: Sitzungscookie weiterleiten

{
  "env": {
    "GRAFANA_URL": "https://grafana.internal",
    "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your token>",
    "GRAFANA_FORWARD_HEADERS": "Cookie"
  }
}

Sie können mehrere Header weiterleiten, indem Sie sie durch Kommas trennen:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

Weitergeleitete Header werden mit den in GRAFANA_EXTRA_HEADERS definierten Headern zusammengeführt. Wenn ein Headername in beiden vorkommt, hat der Wert aus der eingehenden Anfrage für diese Anfrage Vorrang.

Trace-Context-Header (traceparent, tracestate, baggage) bilden eine Ausnahme: Der Server leitet den Trace-Kontext selbst weiter, daher überschreibt ein weitergeleiteter Wert niemals den vom Server eingefügten Wert. Siehe Beobachtbarkeit.

  1. Für die Installation von mcp-grafana stehen mehrere Möglichkeiten zur Verfügung:

    • uvx (empfohlen): Wenn uv installiert ist, ist keine zusätzliche Einrichtung erforderlich — uvx lädt den Server automatisch herunter und führt ihn aus:

      uvx mcp-grafana
      
    • Docker-Image: Verwenden Sie das vorgefertigte Docker-Image von Docker Hub.

      Wichtig: Der Einstiegspunkt des Docker-Images ist standardmäßig so konfiguriert, dass der MCP-Server im SSE-Modus ausgeführt wird. Die meisten Benutzer sollten jedoch den STDIO-Modus für die direkte Integration mit KI-Assistenten wie Claude Desktop verwenden:

      1. STDIO-Modus: Für den stdio-Modus müssen Sie die Standardeinstellung ausdrücklich mit -t stdio überschreiben und das Flag -i hinzufügen, damit stdin geöffnet bleibt:
      docker pull grafana/mcp-grafana
      # For local Grafana:
      docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
      # For Grafana Cloud:
      docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
      

      Hinweis — Netzwerkmodi absichern: Im SSE- und streamable-http-Modus bindet der Container an eine Nicht-Loopback-Adresse (0.0.0.0:8000). Ohne ein Aufrufer-Token startet der Server zwar, protokolliert jedoch einen Sicherheitsfehler (auf Protokollebene error, sodass der Fehler nicht durch --log-level verborgen wird; in einer zukünftigen Hauptversion wird der Server den Start verweigern). Setzen Sie MCP_GRAFANA_SERVER_TOKEN, um von Clients ein Authorization: Bearer <token> zu verlangen (empfohlen). Der STDIO-Modus ist davon nicht betroffen. Siehe Aufruferauthentifizierung.

      1. SSE-Modus: In diesem Modus läuft der Server als HTTP-Server, mit dem sich Clients verbinden. Sie müssen Port 8000 mit dem Flag -p freigeben:
      docker pull grafana/mcp-grafana
      docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
      
      1. Streamable-HTTP-Modus: In diesem Modus läuft der Server als unabhängiger Prozess, der mehrere Clientverbindungen verarbeiten kann. Sie müssen Port 8000 mit dem Flag -p freigeben. Für diesen Modus müssen Sie die Standardeinstellung ausdrücklich mit -t streamable-http überschreiben.
      docker pull grafana/mcp-grafana
      docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http
      

      Für den Streamable-HTTP-Modus mit HTTPS und Server-TLS-Zertifikaten:

      docker pull grafana/mcp-grafana
      docker run --rm -p 8443:8443 \
        -v /path/to/certs:/certs:ro \
        -e GRAFANA_URL=http://localhost:3000 \
        -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
        -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> \
        grafana/mcp-grafana \
        -t streamable-http \
        -addr :8443 \
        --server.tls-cert-file /certs/server.crt \
        --server.tls-key-file /certs/server.key
      
    • Binärdatei herunterladen: Laden Sie die neueste Version von mcp-grafana von der Releases-Seite herunter und legen Sie sie in Ihrem $PATH ab.

    • Aus dem Quellcode erstellen: Wenn Sie eine Go-Toolchain installiert haben, können Sie die Anwendung auch aus dem Quellcode erstellen und installieren. Verwenden Sie dazu die Umgebungsvariable GOBIN, um das Verzeichnis anzugeben, in dem die Binärdatei installiert werden soll. Dieses Verzeichnis sollte sich ebenfalls in Ihrem $PATH befinden.

      GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/v2/cmd/mcp-grafana@latest
      
    • Mit Helm auf Kubernetes bereitstellen: Verwenden Sie das Helm-Chart aus dem Grafana-helm-charts-Repository

      helm repo add grafana https://grafana.github.io/helm-charts
      helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana/grafana-mcp
      
  2. Fügen Sie die Serverkonfiguration zu Ihrer Client-Konfigurationsdatei hinzu. Zum Beispiel für Claude Desktop:

    Bei Verwendung von uvx:

    {
      "mcpServers": {
        "grafana": {
          "command": "uvx",
          "args": ["mcp-grafana"],
          "env": {
            "GRAFANA_URL": "http://localhost:3000",
            "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
          }
        }
      }
    }
    

    Bei Verwendung der Binärdatei:

    {
      "mcpServers": {
        "grafana": {
          "command": "mcp-grafana",
          "args": [],
          "env": {
            "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
            "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
            // If using username/password authentication
            "GRAFANA_USERNAME": "<your username>",
            "GRAFANA_PASSWORD": "<your password>",
            // Optional: specify organization ID for multi-org support
            "GRAFANA_ORG_ID": "1"
          }
        }
      }
    }
    

Hinweis: Wenn Sie in Claude Desktop Error: spawn mcp-grafana ENOENT sehen, müssen Sie den vollständigen Pfad zu mcp-grafana angeben.

Bei Verwendung von Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>",
        // If using username/password authentication
        "GRAFANA_USERNAME": "<your username>",
        "GRAFANA_PASSWORD": "<your password>",
        // Optional: specify organization ID for multi-org support
        "GRAFANA_ORG_ID": "1"
      }
    }
  }
}

Hinweis: Das Argument -t stdio ist hier unerlässlich, da es den standardmäßigen SSE-Modus im Docker-Image überschreibt.

VSCode mit einem Remote-MCP-Server verwenden

Wenn Sie VSCode verwenden und den MCP-Server im SSE-Modus ausführen (der standardmäßig verwendet wird, wenn das Docker-Image ohne Überschreiben des Transports genutzt wird), stellen Sie sicher, dass Ihr .vscode/settings.json Folgendes enthält:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

Für den HTTPS-Modus mit streamable HTTP und Server-TLS-Zertifikaten:

"mcp": {
  "servers": {
    "grafana": {
      "type": "sse",
      "url": "https://localhost:8443/sse"
    }
  }
}

Debug-Modus

Sie können den Debug-Modus für den Grafana-Transport aktivieren, indem Sie der Befehlszeile das Flag -debug hinzufügen. Dadurch werden HTTP-Anfragen und -Antworten zwischen dem MCP-Server und der Grafana-API detailliert protokolliert, was bei der Fehlerbehebung hilfreich sein kann.

Um den Debug-Modus mit der Claude-Desktop-Konfiguration zu verwenden, aktualisieren Sie Ihre Konfiguration wie folgt:

Bei Verwendung der Binärdatei:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["-debug"],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Bei Verwendung von Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "-debug"
      ],
      "env": {
        "GRAFANA_URL": "http://localhost:3000",  // Or "https://myinstance.grafana.net" for Grafana Cloud
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Hinweis: Wie bei der Standardkonfiguration ist das Argument -t stdio erforderlich, um den standardmäßigen SSE-Modus im Docker-Image zu überschreiben.

TLS-Konfiguration

Wenn sich Ihre Grafana-Instanz hinter mTLS befindet oder benutzerdefinierte TLS-Zertifikate erfordert, können Sie den MCP-Server so konfigurieren, dass er benutzerdefinierte Zertifikate verwendet. Der Server unterstützt die folgenden TLS-Konfigurationsoptionen:

  • --tls-cert-file: Pfad zur TLS-Zertifikatsdatei für die Client-Authentifizierung
  • --tls-key-file: Pfad zur privaten TLS-Schlüsseldatei für die Client-Authentifizierung
  • --tls-ca-file: Pfad zur TLS-CA-Zertifikatsdatei für die Serverüberprüfung
  • --tls-skip-verify: TLS-Zertifikatsüberprüfung überspringen (unsicher, nur zu Testzwecken verwenden)

Beispiel mit Client-Zertifikatsauthentifizierung:

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [
        "--tls-cert-file",
        "/path/to/client.crt",
        "--tls-key-file",
        "/path/to/client.key",
        "--tls-ca-file",
        "/path/to/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Beispiel mit Docker:

{
  "mcpServers": {
    "grafana": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/certs:/certs:ro",
        "-e",
        "GRAFANA_URL",
        "-e",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN",
        "grafana/mcp-grafana",
        "-t",
        "stdio",
        "--tls-cert-file",
        "/certs/client.crt",
        "--tls-key-file",
        "/certs/client.key",
        "--tls-ca-file",
        "/certs/ca.crt"
      ],
      "env": {
        "GRAFANA_URL": "https://secure-grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "<your service account token>"
      }
    }
  }
}

Die TLS-Konfiguration wird auf alle vom MCP-Server verwendeten HTTP-Clients angewendet, darunter:

  • Der zentrale Grafana-OpenAPI-Client
  • Prometheus-Datenquellen-Clients
  • Loki-Datenquellen-Clients
  • Incident-Management-Clients
  • Alerting-Clients
  • Asserts-Clients

Beispiele für die direkte CLI-Verwendung:

Zum Testen mit selbstsignierten Zertifikaten:

./mcp-grafana --tls-skip-verify -debug

Mit Client-Zertifikatsauthentifizierung:

./mcp-grafana \
  --tls-cert-file /path/to/client.crt \
  --tls-key-file /path/to/client.key \
  --tls-ca-file /path/to/ca.crt \
  -debug

Nur mit benutzerdefiniertem CA-Zertifikat:

./mcp-grafana --tls-ca-file /path/to/ca.crt

Programmgesteuerte Verwendung:

Wenn Sie diese Bibliothek programmgesteuert verwenden, können Sie auch TLS-fähige Kontextfunktionen erstellen:

// Using struct literals
tlsConfig := &mcpgrafana.TLSConfig{
    CertFile: "/path/to/client.crt",
    KeyFile:  "/path/to/client.key",
    CAFile:   "/path/to/ca.crt",
}
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug:     true,
    TLSConfig: tlsConfig,
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

// Or inline
grafanaConfig := mcpgrafana.GrafanaConfig{
    Debug: true,
    TLSConfig: &mcpgrafana.TLSConfig{
        CertFile: "/path/to/client.crt",
        KeyFile:  "/path/to/client.key",
        CAFile:   "/path/to/ca.crt",
    },
}
contextFunc := mcpgrafana.ComposedStdioContextFunc(grafanaConfig)

URL-Validierung:

Wenn Sie NewGrafanaClient direkt aufrufen (stdio oder programmgesteuerte Erstellung), validieren Sie URLs vorab, um einen erreichbaren Panic zu vermeiden:

if err := mcpgrafana.ValidateGrafanaURL(urlFromHeader); err != nil {
    http.Error(w, err.Error(), http.StatusBadRequest)
    return
}
client := mcpgrafana.NewGrafanaClient(ctx, urlFromHeader, apiKey, nil)

Server-TLS-Konfiguration (nur für den Streamable-HTTP-Transport)

Bei Verwendung des Streamable-HTTP-Transports (-t streamable-http) können Sie den MCP-Server so konfigurieren, dass er HTTPS statt HTTP bereitstellt. Dies ist nützlich, wenn Sie die Verbindung zwischen Ihrem MCP-Client und dem Server selbst absichern müssen.

Der Server unterstützt die folgenden TLS-Konfigurationsoptionen für den Streamable-HTTP-Transport:

  • --server.tls-cert-file: Pfad zur TLS-Zertifikatsdatei für HTTPS auf dem Server (für TLS erforderlich)
  • --server.tls-key-file: Pfad zur privaten TLS-Schlüsseldatei für HTTPS auf dem Server (für TLS erforderlich)

Hinweis: Diese Flags sind vollständig von den oben dokumentierten Client-TLS-Flags getrennt. Die Client-TLS-Flags konfigurieren, wie der MCP-Server eine Verbindung zu Grafana herstellt, während diese Server-TLS-Flags konfigurieren, wie Clients bei Verwendung des Streamable-HTTP-Transports eine Verbindung zum MCP-Server herstellen.

Beispiel mit einem HTTPS-Server für Streamable HTTP:

./mcp-grafana \
  -t streamable-http \
  --server.tls-cert-file /path/to/server.crt \
  --server.tls-key-file /path/to/server.key \
  -addr :8443

Dadurch wird der MCP-Server auf dem HTTPS-Port 8443 gestartet. Clients würden dann eine Verbindung zu https://localhost:8443/ statt zu http://localhost:8000/ herstellen.

Docker-Beispiel mit Server-TLS:

docker run --rm -p 8443:8443 \
  -v /path/to/certs:/certs:ro \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

Health-Check-Endpunkt

Bei Verwendung der SSE- (-t sse) oder Streamable-HTTP-Transporte (-t streamable-http) stellt der MCP-Server unter /healthz einen Health-Check-Endpunkt bereit. Load-Balancer, Überwachungssysteme oder Orchestrierungsplattformen können diesen Endpunkt verwenden, um zu überprüfen, ob der Server läuft und Verbindungen annimmt.

Endpunkt: GET /healthz

Antwort:

  • Statuscode: 200 OK
  • Inhalt: ok

Beispielverwendung:

# For streamable HTTP or SSE transport on default port
curl http://localhost:8000/healthz

# Probe a side listener while MCP stays on loopback (Kubernetes + sidecar)
./mcp-grafana -t streamable-http --address 127.0.0.1:8000 --healthz-address :8080
curl http://127.0.0.1:8080/healthz

# With --base-path /my-base the MCP routes move under the prefix
# (/my-base/sse, /my-base/mcp), but healthz does not:
curl http://localhost:8000/healthz          # 200 ok
curl http://localhost:8000/my-base/healthz  # 404

Hinweis: Der Health-Check-Endpunkt ist nur bei Verwendung der SSE- oder Streamable-HTTP-Transporte verfügbar. Bei Verwendung des stdio-Transports (-t stdio) ist er nicht verfügbar, da stdio keinen HTTP-Server bereitstellt.

Anonyme Nutzungsstatistiken

Der Server kann Grafana Labs anonyme Nutzungsstatistiken über sich selbst melden: welche Tools aufgerufen wurden, wie viele dieser Aufrufe fehlgeschlagen sind und wie der Server konfiguriert ist. Jeder Bericht umfasst einen Server-Prozess – nicht einen Benutzer und nicht eine Unterhaltung – und wird alle 4 Stunden sowie einmal beim Herunterfahren gesendet. Die Berichterstellung ist standardmäßig aktiviert. Um sie zu deaktivieren, setzen Sie --usage-stats=disabled, GRAFANA_USAGE_STATS=disabled oder DO_NOT_TRACK=1.

Tool-Argumente, Ressourcennamen, Abfragen, Protokollzeilen, Fehlermeldungen und Anmeldedaten werden niemals gesendet. Flags werden nur anhand ihres Namens erfasst, niemals anhand ihres Werts, und die Grafana-Instanz wird lediglich als cloud oder self_hosted beschrieben – niemals anhand von URL, Hostname, Stack-Slug oder Organisation. Die Erfassung erfolgt weder pro Benutzer noch pro Sitzung oder Client: Es gibt keine Sitzungskennung auf der Leitung und keine Möglichkeit, einen Tool-Aufruf einem bestimmten Client zuzuordnen.

# Turn reporting on
mcp-grafana --usage-stats=enabled

# Turn it off (or GRAFANA_USAGE_STATS=disabled)
mcp-grafana --usage-stats=disabled

# Print what would be sent, to stderr, and send nothing
GRAFANA_USAGE_STATS=log mcp-grafana

DO_NOT_TRACK=1 deaktiviert die Berichterstellung ebenfalls und folgt damit der toolübergreifenden Konvention DO_NOT_TRACK. Nur 1 hat eine Wirkung und kann die Berichterstellung nur deaktivieren. Sowohl --usage-stats als auch GRAFANA_USAGE_STATS setzen es außer Kraft, sodass ein Host, der es global festlegt, einen einzelnen Server dennoch wieder aktivieren kann.

GRAFANA_USAGE_STATS_ENDPOINT ändert das Ziel. Es deaktiviert die Berichterstellung nicht.

Die vollständige Feldliste, Informationen dazu, was niemals gesendet wird, sowie Hinweise zum Lesen der Daten und zu ihren Einschränkungen finden Sie unter Anonyme Nutzungsstatistiken.

Beobachtbarkeit

Der MCP-Server unterstützt Prometheus-Metriken, verteiltes OpenTelemetry-Tracing und den Export von OpenTelemetry-Protokollen gemäß den OTel-MCP-Semantikkonventionen. Tracing und Protokollexport werden über standardmäßige OTEL_*-Umgebungsvariablen konfiguriert und funktionieren mit jedem Transport.

Hinweis: mcp-grafana unterstützt derzeit für Traces und Protokolle nur den OTLP/gRPC-Transport. OTEL_EXPORTER_OTLP_PROTOCOL (und seine Varianten _TRACES_PROTOCOL / _LOGS_PROTOCOL) werden nicht berücksichtigt – unabhängig davon wird gRPC verwendet.

Metriken

Bei Verwendung der SSE- oder Streamable-HTTP-Transporte können Sie Prometheus-Metriken mit dem Flag --metrics aktivieren:

# Metrics served on the main server at /metrics
./mcp-grafana -t streamable-http --metrics

# Metrics served on a separate address
./mcp-grafana -t streamable-http --metrics --metrics-address :9090

Verfügbare Metriken:

MetrikTypBeschreibung
mcp_server_operation_duration_secondsHistogrammDauer von MCP-Operationen (Labels: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
http_server_request_duration_secondsHistogrammDauer von HTTP-Serveranfragen (von otelhttp)

Hinweis: Metriken sind nur bei Verwendung der SSE- oder Streamable-HTTP-Transporte verfügbar. Beim stdio-Transport sind sie nicht verfügbar.

Wenn die Loki-Kostenbegrenzung (--loki-guardrail-mode) aktiviert ist, erfassen vier weitere Zähler ihre Entscheidungen:

MetrikTypBeschreibung
mcp_loki_guardrail_admitted_totalZählerAbfragen, die alle aktivierten Prüfungen bestanden haben (Labels: backend)
mcp_loki_guardrail_would_block_totalZählerAbfragen, bei denen eine Prüfung im Modus shadow fehlschlug, die aber trotzdem ausgeführt wurden (Labels: backend, reason)
mcp_loki_guardrail_blocked_totalZählerIm Modus enforce abgelehnte Abfragen (Labels: backend, reason)
mcp_loki_guardrail_fail_open_totalZählerAbfragen, die von der Kostenbegrenzung nicht ausgewertet werden konnten und zugelassen wurden (Labels: backend, cause)

reason ist einer der Werte selector, range, bytes; cause ist einer der Werte unparseable, estimate_failed; backend ist einer der Werte loki, victorialogs, unknown. Eine Abfrage, die mehrere Prüfungen auslöst, wird einmal gezählt und mit der zuerst ausgeführten Prüfung gekennzeichnet (selector, dann range, dann bytes), sodass die vier Zähler die überwachte Abfragemenge vollständig aufteilen. Unter Beobachtbarkeit erfahren Sie, wie Sie die Werte während eines Rollouts von shadow → enforce interpretieren.

Wenn die Prometheus-Kostenbegrenzung (--prometheus-guardrail-mode) aktiviert ist, erfassen vier Zähler ihre Entscheidungen auf dieselbe Weise:

MetrikTypBeschreibung
mcp_prometheus_guardrail_admitted_totalZählerAbfragen, die alle aktivierten Prüfungen bestanden haben
mcp_prometheus_guardrail_would_block_totalZählerAbfragen, bei denen eine Prüfung im Modus shadow fehlschlug, die aber trotzdem ausgeführt wurden (Labels: reason)
mcp_prometheus_guardrail_blocked_totalZählerIm Modus enforce abgelehnte Abfragen (Labels: reason)
mcp_prometheus_guardrail_fail_open_totalZählerAbfragen, die trotz einer nicht verfügbaren aktivierten Bewertung zugelassen wurden (Labels: reason)

reason ist selector, range, points oder cardinality bei would_block und blocked; die Abfrage wird einmal unter der ersten Prüfung gezählt, die in dieser Reihenfolge fehlschlug. fail_open verwendet unparseable oder cardinality_unknown. Die optionale Kardinalitätsrichtlinie verwendet zwischengespeicherte Top-N-TSDB-Statistiken, um für bekannte Metriken mit hoher Kardinalität einen expliziten Geltungsbereich zu verlangen. Sie schätzt weder die ausgewählten Zeitreihen noch weist sie nach, dass fehlende Metriken unbedenklich sind. Nicht unterstützte TSDB-Endpunkte führen dazu, dass diese Richtlinie Abfragen zulässt. Es gibt kein Label backend.

Bibliothekseinbettungen sollten GrafanaConfig.MeterProvider festlegen (das Gegenstück zu GrafanaConfig.Logger für Metriken): Die Kostenbegrenzung wird innerhalb eines Tool-Handlers ausgeführt und hat daher keine Konstruktoroption. Ein Prozess, der einen globalen No-op-MeterProvider installiert, würde andernfalls sämtliche Aufzeichnungen verwerfen.

Protokollierung langsamer Anfragen

Das Flag --slow-request-threshold gibt ein strukturiertes Protokollereignis aus, sobald eine MCP-Anfrage (Tool-Aufruf, Auflistung, Ressourcenlesevorgang usw.) die angegebene Dauer überschreitet. Es ist hilfreich, um langsame Abfragen und Tool-Aufrufe zu diagnostizieren, ohne das vollständige Debug-Protokoll mit Einträgen zu überfluten.

# Warn on any request slower than 500ms (works on all transports)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms

# Same thing on stdio (the feature is transport-agnostic, unlike --metrics)
./mcp-grafana -t stdio --slow-request-threshold 500ms

# Log at INFO level instead of WARN (useful during investigation)
./mcp-grafana -t streamable-http --slow-request-threshold 500ms --slow-request-log-level info

Das Protokollereignis enthält die folgenden strukturierten Attribute:

AttributBeschreibung
mcp.methodDie MCP-Methode (z. B. tools/call, tools/list, resources/read)
durationBeobachtete Anfragedauer
thresholdKonfigurierter Schwellenwert
toolTool-Name (nur bei Methoden vom Typ tools/call vorhanden)
errorFehlerwert, wenn die Anfrage fehlgeschlagen ist (Kontext nach bestem Bemühen; der Inhalt wird durch die vorgelagerte Fehlerbehandlung bestimmt)
error.typeFehlerklassifizierung mit begrenzter Kardinalität (_OTHER bei nicht typisierten Fehlern)

Die Protokollierung langsamer Anfragen funktioniert mit allen Transporten (einschließlich stdio) und erfordert --metrics nicht. Der Standard-Schwellenwert 0 deaktiviert sie vollständig. Proxied Tools laufen über tools/call und werden automatisch erfasst.

Tracing

Verteiltes Tracing wird über standardmäßige OTEL_*-Umgebungsvariablen konfiguriert und funktioniert unabhängig vom Flag --metrics. Wenn OTEL_EXPORTER_OTLP_ENDPOINT (oder das signalspezifische OTEL_EXPORTER_OTLP_TRACES_ENDPOINT) gesetzt ist, exportiert der Server Traces über OTLP/gRPC:

# Send traces to a local Tempo instance
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

# Send traces to Grafana Cloud with authentication
OTEL_EXPORTER_OTLP_ENDPOINT=https://tempo-us-central1.grafana.net:443 \
OTEL_EXPORTER_OTLP_HEADERS="Authorization=Basic ..." \
./mcp-grafana -t streamable-http

Tool-Aufruf-Spans folgen der SemConv-Benennung (tools/call <tool_name>) und enthalten Attribute wie gen_ai.tool.name, mcp.method.name und mcp.session.id. Der Server unterstützt außerdem die Weitergabe des W3C-Trace-Kontexts aus dem Feld _meta von Tool-Aufrufanfragen.

Protokolle

Wenn OTEL_EXPORTER_OTLP_ENDPOINT (oder das signalspezifische OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) gesetzt ist, exportiert der Server zusätzlich zur bestehenden Klartextausgabe auf stderr strukturierte Logs über OTLP/gRPC. Die otelslog-Bridge fügt automatisch trace_id und span_id aus dem aktiven Span hinzu, sodass Logeinträge mit den Traces korrelieren, die der Server bereits ausgibt.

Traces und Logs lösen ihre Endpunkte unabhängig voneinander auf, sodass die beiden Signale separat aktiviert werden können: Wenn nur OTEL_EXPORTER_OTLP_TRACES_ENDPOINT gesetzt wird, ist Tracing ohne Logexport aktiviert; wenn nur OTEL_EXPORTER_OTLP_LOGS_ENDPOINT gesetzt wird, ist der Logexport ohne Tracing aktiviert; und OTEL_EXPORTER_OTLP_ENDPOINT aktiviert beides.

Wenn Sie das generische OTEL_EXPORTER_OTLP_ENDPOINT verwenden, den Logexport aber deaktivieren möchten (z. B. weil Ihr Backend LogsService nicht unterstützt), setzen Sie:

OTEL_LOGS_EXPORTER=none

Dadurch wird verhindert, dass der Server unabhängig von der Endpunktkonfiguration einen OTLP-Logs-Exporter erstellt. So werden Fehler wie unknown service opentelemetry.proto.collector.logs.v1.LogsService vermieden.

Die Protokollierung auf stderr bleibt unverändert, wenn OTLP-Logging aktiviert ist. Sie können weiterhin Container-Logs verwenden oder stderr an /dev/null weiterleiten.

# Send both logs and traces to a local OTel collector
OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317 \
OTEL_EXPORTER_OTLP_INSECURE=true \
./mcp-grafana -t streamable-http

Das Transportprotokoll ist OTLP/gRPC (Standardport 4317). Logs können direkt an jedes verwaltete Backend gesendet werden, das OTLP/gRPC akzeptiert – zum Beispiel Grafana Cloud –, indem Sie OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (oder das generische OTEL_EXPORTER_OTLP_ENDPOINT) auf den Remote-gRPC-Endpunkt setzen und die Authentifizierung über OTEL_EXPORTER_OTLP_LOGS_HEADERS (oder OTEL_EXPORTER_OTLP_HEADERS) bereitstellen, wie im obigen Tracing-Beispiel. Ein lokaler OTel Collector ist optional – er ist für Fan-out, Batching oder das Routing an mehrere Backends nützlich, aber nicht erforderlich.

Die signalspezifischen Varianten OTEL_EXPORTER_OTLP_LOGS_ENDPOINT, OTEL_EXPORTER_OTLP_LOGS_HEADERS, OTEL_EXPORTER_OTLP_LOGS_INSECURE, OTEL_EXPORTER_OTLP_LOGS_CERTIFICATE, OTEL_EXPORTER_OTLP_LOGS_TIMEOUT und OTEL_EXPORTER_OTLP_LOGS_COMPRESSION werden berücksichtigt und haben Vorrang vor ihren generischen Gegenstücken OTEL_EXPORTER_OTLP_*. Die vollständige Liste und die Rangfolgeregeln finden Sie in der OTel-Exporter-Spezifikation.

Wenn der konfigurierte Collector nicht erreichbar ist, werden Logeinträge im Arbeitsspeicher gepuffert (Standardwarteschlange: 2048). Sobald die Warteschlange voll ist, werden die ältesten Einträge verworfen. Der Prozess läuft weiter, ohne den Dienst zu blockieren. Konfigurieren Sie einen lokalen OTel Collector, wenn Sie bei Ausfällen eine verlustfreie Pufferung benötigen.

Logs werden auch über den stdio-Transport exportiert. So lassen sich Logs lokaler mcp-grafana-Instanzen, die von IDE-Clients aufgerufen werden, einfach zentralisieren.

Docker-Beispiel mit Metriken, Tracing und Logs:

docker run --rm -p 8000:8000 \
  -e GRAFANA_URL=http://localhost:3000 \
  -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your token> \
  -e OTEL_EXPORTER_OTLP_ENDPOINT=http://tempo:4317 \
  -e OTEL_EXPORTER_OTLP_INSECURE=true \
  grafana/mcp-grafana \
  -t streamable-http --metrics

Durchsetzung von Prometheus-Abfragebeschränkungen

--prometheus-enforced-matchers ermöglicht es einem Betreiber, einzuschränken, welche Prometheus-Zeitreihen native Prometheus-Tools lesen können. Dazu wird eine feste Gruppe von PromQL-Label-Matchern per AND-Verknüpfung in jeden Vektor-Selektor jeder vom Server ausgeführten nativen Prometheus-Abfrage eingefügt. Das ist nützlich, wenn eine Datenquelle Zeitreihen enthält, die nicht offengelegt werden dürfen (z. B. Metriken mit sensiblen Mandanten- oder Kundenlabels), der Zugriff auf der Prometheus-Ebene aber nicht eingeschränkt werden kann.

# Only ever read prod/staging environments (allowlist)
./mcp-grafana --prometheus-enforced-matchers 'environment=~"prod|staging"' --disable-api --disable-rendering --disable-assistant

# Never read the vault or payments namespaces (exclusion)
./mcp-grafana --prometheus-enforced-matchers 'namespace!~"vault|payments"' --disable-api --disable-rendering --disable-assistant

Funktionsweise:

  • Die Matcher werden beim Start einmal geparst (ungültige Eingaben verhindern den Serverstart) und jedem Vektor-Selektor jeder Abfrage hinzugefügt. Eine Benutzerabfrage kann die Ergebnisse innerhalb der durchgesetzten Grenzen nur weiter einschränken, niemals erweitern.
  • Die Funktion gilt für query_prometheus, query_prometheus_histogram und Prometheus-Panels in run_panel_query.
  • Bei der nativen Prometheus-Erkennung über list_prometheus_label_names, list_prometheus_label_values und list_prometheus_metric_names werden die Matcher ebenfalls auf jeden Zeitreihen-Selektor angewendet, auch wenn kein Selektor angegeben ist.
  • list_prometheus_metric_metadata wird bei aktivierter Durchsetzung abgelehnt: Der Metadaten-Endpunkt von Prometheus kann nicht nach Zeitreihenlabels filtern und führt Metadaten aus mehreren Zielen zusammen. Auch die Erkennung über Cloud Monitoring wird abgelehnt, da dessen Erkennungs-APIs nicht die vollständige Prometheus-Matcher-Richtlinie anwenden können.
  • Die Funktion schlägt geschlossen fehl: Abfragen, die nicht geparst werden können, werden abgelehnt, statt ungefiltert gesendet zu werden.

[!IMPORTANT] Andere aktivierte Tools können diese Matcher umgehen. Deaktivieren Sie grafana_api_request mit --disable-api, Rendering-Tools mit --disable-rendering und Grafana Assistant mit --disable-assistant (oder --disable-write). Insbesondere kann render_grafana_app ungefilterte Prometheus-Abfragen über seine query_datasource-Quelle senden. --disable-dsquery schließt diese Quelle, deaktiviert aber nicht das serverseitige Panel-Rendering. Vorhandene Dashboard-Snapshots können ebenfalls uneingeschränkte Daten enthalten. Verwenden Sie in diesem Fall --disable-snapshot.

Durchsetzung von Loki-Abfragebeschränkungen

--loki-enforced-matchers ermöglicht es einem Betreiber, einzuschränken, welche Loki-Logstreams der Server überhaupt lesen kann. Dazu wird eine feste Gruppe von LogQL-Label-Matchern per AND-Verknüpfung in jede vom Server ausgeführte native Loki-Abfrage eingefügt. Das ist nützlich, wenn eine Datenquelle Streams enthält, die nicht offengelegt werden dürfen (z. B. Logs mit möglicherweise sensiblen Informationen), der Zugriff auf der Grafana- oder Loki-Ebene aber nicht eingeschränkt werden kann (OSS bietet keine Label-Zugriffskontrolle pro Datenquelle oder Benutzer).

# Only ever read prod/staging environments (allowlist)
./mcp-grafana --loki-enforced-matchers 'environment=~"prod|staging"' --disable-api

# Never read the vault or payments namespaces (exclusion)
./mcp-grafana --loki-enforced-matchers 'namespace!~"vault|payments"' --disable-api

Funktionsweise:

  • Die Matcher werden beim Start einmal geparst (ungültige Eingaben verhindern den Serverstart) und jedem Stream-Selektor jeder Abfrage hinzugefügt. Da Loki Matcher innerhalb eines Selektors mit AND verknüpft, kann eine Benutzerabfrage die Ergebnisse innerhalb der durchgesetzten Grenzen nur weiter einschränken, niemals erweitern. Ein Benutzer-Selektor, der der Richtlinie widerspricht (z. B. eine Abfrage nach {namespace="vault"} bei aktivierter Ausschlussregel), liefert einfach keine Ergebnisse.
  • Die Funktion gilt für query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names und list_loki_label_values.
  • Die Funktion schlägt geschlossen fehl: Abfragen, die nicht geparst werden können, werden abgelehnt, statt ungefiltert gesendet zu werden.
  • VictoriaLogs-Datenquellen verwenden LogsQL, das sich nicht sicher umschreiben lässt. Daher werden sie bei aktivierter Durchsetzung vollständig abgelehnt.
  • Rein negative Matcher können die Label-Aufzählungsendpunkte nicht einschränken (Loki lehnt einen eigenständigen Selektor ohne positiven Matcher ab). Steuern Sie diesen Sonderfall mit --loki-label-enumeration-fallback (reject ist die Standardeinstellung; mit unfiltered wird eine nicht eingeschränkte Aufzählung von Label-Metadaten erlaubt – Logzeilen werden niemals offengelegt). Positive Matcher und Allowlist-Matcher sind davon nicht betroffen.

[!IMPORTANT] Die Durchsetzung gilt nur für die Loki-Abfragetools. Andere Tools können über Pfade, die das durchgesetzte Backend nicht verwenden, auf Loki-Logdaten zugreifen. Damit die Einschränkung tatsächlich greift, müssen Sie diese Tools daher ebenfalls deaktivieren:

  • --disable-api — grafana_api_request kann den Loki-Datenquellen-Proxy direkt abfragen (vollständige Umgehung).
  • --disable-rendering — get_panel_image rendert Loki-Panels serverseitig und erzeugt Bilder mit uneingeschränkten Logzeilen.
  • --disable-assistant — ask_assistant delegiert an Grafana Assistant, der serverseitig alle Loki-Streams liest. Dieses Tool wird nur registriert, wenn Schreibtools aktiviert sind. Daher wird es ebenfalls durch --disable-write deaktiviert.

Der Server protokolliert beim Start eine Warnung, in der jedes dieser weiterhin aktivierten Tools genannt wird. run_panel_query ist sicher (es verwendet den durchgesetzten Abfragepfad erneut). Tempo-Tools fragen Traces und keine Loki-Logs ab und stellen daher keine Umgehungsmöglichkeit dar. Dashboard-Snapshots (--disable-snapshot) können ebenfalls Log-Panel-Daten enthalten, die außerhalb der Durchsetzung erfasst wurden.

Fehlerbehebung

Grafana-Versionskompatibilität

Wenn bei der Verwendung von Tools für Datenquellen der folgende Fehler auftritt:

get datasource by uid : [GET /datasources/uid/{uid}][400] getDataSourceByUidBadRequest {"message":"id is invalid"}

Dies weist in der Regel darauf hin, dass Sie eine Grafana-Version vor 9.0 verwenden. Der API-Endpunkt /datasources/uid/{uid} wurde in Grafana 9.0 eingeführt. Daher schlagen Datenquellenoperationen in früheren Versionen fehl.

Lösung: Aktualisieren Sie Ihre Grafana-Instanz auf Version 9.0 oder höher, um dieses Problem zu beheben.

Entwicklung

Beiträge sind willkommen! Lesen Sie zuerst CONTRIBUTING.md – dort erfahren Sie, was in diesen Server gehört und wie Sie Vorschläge einreichen können.

Wenn Sie ein neues Tool hinzufügen, reichen Sie bitte einen Tool-Vorschlag ein, bevor Sie mit dem Programmieren beginnen. Jedes standardmäßig aktivierte Tool wird bei jeder Anfrage an das Modell gesendet. Daher besprechen wir die Idee lieber vorab, als einen fertigen Pull Request abzulehnen. Für Fehlerbehebungen, Dokumentation, Tests und neue Parameter für bestehende Tools ist kein Vorschlag erforderlich – reichen Sie einfach einen PR ein.

Dieses Projekt ist in Go geschrieben. Tool-Versionen und Entwicklungsaufgaben sind in mise.toml hinterlegt: Installieren Sie mise, führen Sie mise install aus, um die festgelegten Tools abzurufen, und mise tasks, um die Aufgaben aufzulisten.

Um den Server lokal im STDIO-Modus auszuführen (dem Standard für die lokale Entwicklung), verwenden Sie:

mise run run

Um den Server lokal im SSE-Modus auszuführen, verwenden Sie:

go run ./cmd/mcp-grafana --transport sse

Sie können den Server auch mit dem SSE-Transport in einem benutzerdefinierten Docker-Image ausführen. Wie beim veröffentlichten Docker-Image ist der Einstiegspunkt dieses benutzerdefinierten Images standardmäßig auf den SSE-Modus eingestellt. Erstellen Sie das Image mit:

mise run build-image

Führen Sie das Image im SSE-Modus (dem Standard) mit folgendem Befehl aus:

docker run -it --rm -p 8000:8000 mcp-grafana:latest

Wenn Sie stattdessen den STDIO-Modus verwenden möchten, überschreiben Sie die Transporteinstellung:

docker run -it --rm mcp-grafana:latest -t stdio

Tests

Es gibt drei Arten von Tests:

  1. Unit-Tests (keine externen Abhängigkeiten erforderlich):
mise run test-unit

Sie können Unit-Tests auch mit folgendem Befehl ausführen:

mise run test
  1. Integrationstests (Docker-Container müssen ausgeführt werden):
mise run test-integration
  1. Cloud-Tests (erfordern eine Grafana-Cloud-Instanz und Zugangsdaten):
mise run test-cloud

Hinweis: Cloud-Tests werden in CI automatisch konfiguriert. Für die lokale Entwicklung müssen Sie eine eigene Grafana-Cloud-Instanz und die entsprechenden Zugangsdaten einrichten.

Für umfassendere Integrationstests muss eine Grafana-Instanz lokal auf Port 3000 ausgeführt werden. Sie können sie mit Docker Compose starten:

docker-compose up -d

Wenn Sie weitere Tools hinzufügen, ergänzen Sie bitte auch Integrationstests dafür. Die vorhandenen Tests sind ein guter Ausgangspunkt.

Linting

Führen Sie zum Linten des Codes Folgendes aus:

mise run lint

Dazu gehört ein benutzerdefinierter Linter, der nicht maskierte Kommas in jsonschema-Struct-Tags prüft. Die Kommas in description-Feldern müssen mit \\, maskiert werden, um eine unbemerkte Kürzung zu verhindern. Sie können nur diesen Linter mit folgendem Befehl ausführen:

mise run lint-jsonschema

Weitere Informationen finden Sie in der Dokumentation zum JSONSchema-Linter.

Lizenz

Dieses Projekt ist unter der Apache-Lizenz, Version 2.0 lizenziert.