Grafana

offiziell

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

GitHub

3.5k

Dieses MCP ausprobierenGesponsert

Was kann man mit Grafana MCP machen?

Dashboards suchen und inspizieren — Fragen Sie nach Dashboards anhand von Titel, Ordner, Tag oder Sternstatus und rufen Sie dann Zusammenfassungen oder bestimmte JSONPath-Eigenschaften ab, um das Laden vollständiger JSON-Daten zu vermeiden.
Prometheus und Loki abfragen — Führen Sie PromQL- oder LogQL-Abfragen aus, rufen Sie Metrik-/Label-Metadaten ab und berechnen Sie Histogramm-Perzentile (p50/p95/p99) aus Ihren Datenquellen.
Alerting und Vorfälle verwalten — Listen Sie Alarmregeln und deren Auslösestatus auf, erstellen oder aktualisieren Sie Regeln und suchen oder erstellen Sie Grafana-Incident-Datensätze.
Datenquellen erkunden und SQL ausführen — Listen Sie konfigurierte Datenquellen auf, entdecken Sie Tabellen und Schemata und führen Sie SQL-Abfragen gegen ClickHouse, Snowflake, Athena, MySQL, PostgreSQL oder MSSQL aus.
Dashboards als Bilder rendern — Erzeugen Sie PNG-Snapshots eines Panels oder eines vollständigen Dashboards mit benutzerdefinierten Zeiträumen, Themes und Variablen für Berichte oder Alarme.
Präzise Deeplinks generieren — Erstellen Sie direkte URLs zu Dashboards, Panels oder Explore-Ansichten mit Zeiträumen und Parametern, anstatt Linkformate zu erraten.

Dokumentation

Grafana MCP-Server

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

Dieser bietet Zugriff auf Ihre Grafana-Instanz und das umgebende Ökosystem.

Schnellstart

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

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

Für Grafana Cloud ersetzen Sie GRAFANA_URL durch Ihre Instanz-URL (z. B. https://myinstance.grafana.net). Weitere Installationsoptionen wie Docker, Binärdatei und Helm finden Sie unter Verwendung.

Anforderungen

Grafana Version 9.0 oder höher ist für die volle Funktionalität erforderlich. Einige Funktionen, insbesondere datenquellenbezogene Operationen, funktionieren möglicherweise nicht korrekt mit früheren Versionen, da API-Endpunkte fehlen.

Funktionen

Die folgenden Funktionen sind derzeit im MCP-Server verfügbar. Diese Liste dient nur zu Informationszwecken und stellt keine Roadmap oder Verpflichtung zu zukünftigen Funktionen dar.

Dashboards

Dashboards suchen: Dashboards nach Titel, Ordner-UID, Tag oder Sternstatus finden
Dashboard per UID abrufen: Vollständige Dashboard-Details mithilfe der eindeutigen Kennung abrufen. Optional version übergeben, um eine gespeicherte Momentaufnahme anstelle des aktuellen Dashboards zu laden. Warnung: Große Dashboards können erheblichen Kontextfensterplatz verbrauchen.
Dashboard-Versionen auflisten: Gespeicherte Versionen eines Dashboards als kompakte Metadaten auflisten (Versionsnummer, Autor, Zeitstempel, Speichernachricht)
Dashboard-Zusammenfassung abrufen: Eine kompakte Übersicht eines Dashboards abrufen, einschließlich Titel, Panel-Anzahl, Panel-Typen, Variablen und Metadaten, ohne das vollständige JSON, um die Kontextfensternutzung 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: Bestehende Dashboards ändern oder neue erstellen. Warnung: Erfordert vollständiges Dashboard-JSON, das große Mengen an Kontextfensterplatz verbrauchen kann.
Dashboard patchen: Gezielte Änderungen an einem Dashboard vornehmen, ohne das vollständige JSON zu benötigen, wodurch die Kontextfensternutzung für gezielte Modifikationen erheblich reduziert wird
Panel-Abfragen und Datenquelleninformationen abrufen: Titel, Abfragezeichenfolge und Datenquelleninformationen (einschließlich UID und Typ, falls verfügbar) von jedem Panel in einem Dashboard abrufen

Panel-Abfrage ausführen

Hinweis: Die Tools zur Panel-Abfrageausführung sind standardmäßig deaktiviert. Um sie zu aktivieren, fügen Sie runpanelquery zu Ihrem --enabled-tools-Flag hinzu.

Panel-Abfrage ausführen: Die Abfrage eines Dashboard-Panels mit benutzerdefinierten Zeitbereichen und Variablenüberschreibungen ausführen.

Kontextfensterverwaltung

Die Dashboard-Tools enthalten nun mehrere Strategien zur effektiven Verwaltung der Kontextfensternutzung (Issue #101):

get_dashboard_summary verwenden für Dashboard-Übersicht und Planung von Änderungen
get_dashboard_property mit JSONPath verwenden, wenn Sie nur bestimmte Dashboard-Teile benötigen
get_dashboard_by_uid vermeiden, es sei denn, Sie benötigen speziell das vollständige Dashboard-JSON

Datenquellen

Datenquelleninformationen auflisten und abrufen: Alle konfigurierten Datenquellen anzeigen und detaillierte Informationen zu jeder abrufen.
- Unterstützte Datenquellentypen: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Abfragebeispiele

Hinweis: Die Tools für Abfragebeispiele sind standardmäßig deaktiviert. Um sie zu aktivieren, fügen Sie examples zu Ihrem --enabled-tools-Flag hinzu.

Abfragebeispiele abrufen: Beispielabfragen für verschiedene Datenquellentypen abrufen, um die Abfragesyntax zu erlernen.

Prometheus-Abfragen

Prometheus abfragen: PromQL-Abfragen ausführen (unterstützt sowohl Sofort- als auch Bereichsmetrikabfragen) gegen Prometheus-Datenquellen.
Prometheus-Metadaten abfragen: Metrikmetadaten, Metriknamen, Labelnamen und Labelwerte von 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 Protokollabfragen als auch Metrikabfragen mit LogQL gegen Loki-Datenquellen ausführen.
Loki-Metadaten abfragen: Labelnamen, Labelwerte und Stream-Statistiken von 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. Um sie zu aktivieren, fügen Sie influxdb zu Ihrem --enabled-tools-Flag hinzu.

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

SQL-Datenquellenabfragen

Hinweis: SQL-Tools sind standardmäßig deaktiviert. Um sie zu aktivieren, fügen Sie sql zu Ihrem --enabled-tools-Flag hinzu. Die Abwärtskompatibilitäts-Aliasse clickhouse, snowflake und athena funktionieren ebenfalls.

Einheitliche SQL-Tools unterstützen ClickHouse, Snowflake, Athena, MySQL, PostgreSQL und MSSQL über einen einzigen Satz von Tools. Abfragen laufen über die Datenquellen-Plugins von Grafana, sodass die Authentifizierung durch die Datenquellenkonfiguration erfolgt – Anmeldeinformationen werden vom MCP-Server nie gesehen.

Datenbanken/Schemas/Kataloge auflisten: Organisationseinheiten für eine SQL-Datenquelle entdecken. Bei Athena das Katalogfeld weglassen, um Kataloge aufzulisten, oder einen Katalog übergeben, um Datenbanken aufzulisten.
Tabellen auflisten: Tabellen in einer Datenbank oder einem Schema mit Metadaten auflisten (Zeilenanzahl, Größen, sofern verfügbar).
Tabellenschema beschreiben: Spaltennamen, Typen, Nullbarkeit, Standardwerte und Kommentare abrufen.
SQL abfragen: SQL-Abfragen mit datenquellenspezifischer Makrosubstitution ($__timeFilter(col), $__from/$__to, $__interval, ${varname}), automatischer Limit-Durchsetzung und Unterstützung für Vorlagenvariablen ausführen.

CloudWatch-Abfragen

Hinweis: CloudWatch-Tools sind standardmäßig deaktiviert. Um sie zu aktivieren, fügen Sie cloudwatch zu Ihrem --enabled-tools-Flag hinzu.

CloudWatch-Namespaces auflisten: Verfügbare AWS-CloudWatch-Namespaces entdecken.
CloudWatch-Metriken auflisten: In einem bestimmten Namespace verfügbare Metriken auflisten.
CloudWatch-Dimensionen auflisten: Dimensionen zum Filtern von Metrikabfragen abrufen.
CloudWatch abfragen: CloudWatch-Metrikabfragen mit Zeitbereichsunterstützung ausführen.

Google Cloud Logging-Abfragen

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

Cloud Logging-Projekte auflisten: Die GCP-Projekt-IDs entdecken, aus denen die Datenquelle Protokolle lesen kann.
Cloud Logging-Buckets und -Ansichten auflisten: Protokoll-Buckets und Protokoll-Ansichten entdecken, um eine Abfrage einzugrenzen.
Cloud Logging abfragen: Cloud Logging-Abfragesprachenfilter ausführen (z. B. resource.type="k8s_container" AND severity>=ERROR) mit Zeitbereich und Limit; gibt Einträge neueste zuerst mit Schweregrad, Text, Labels und Trace-ID zurück. Die GCP-Authentifizierung wird von der Datenquellenkonfiguration übernommen.

Graphite-Abfragen

Hinweis: Graphite-Tools sind standardmäßig deaktiviert. Um sie zu aktivieren, fügen Sie graphite zu Ihrem --enabled-tools-Flag hinzu.

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

Elasticsearch/OpenSearch-Abfragen

Hinweis: Elasticsearch/OpenSearch-Tools sind standardmäßig deaktiviert. Um sie zu aktivieren, fügen Sie elasticsearch zu Ihrem --enabled-tools-Flag hinzu.

Elasticsearch/OpenSearch abfragen: Suchabfragen gegen Elasticsearch- oder OpenSearch-Datenquellen ausführen, entweder mit Lucene-Abfragesyntax oder Elasticsearch-Abfrage-DSL. Unterstützt Filterung nach Zeitbereich und Abrufen von Protokollen, Metriken oder beliebigen indizierten Daten. Gibt Dokumente mit Index, ID, Quellfeldern und optionalem Relevanzwert zurück.

Quickwit-Abfragen

Hinweis: Quickwit-Tools sind standardmäßig deaktiviert. Um sie zu aktivieren, fügen Sie quickwit zu Ihrem --enabled-tools-Flag hinzu.

Quickwit abfragen: Suchabfragen gegen Quickwit-Datenquellen mit Lucene-Abfragesyntax oder teilweiser Elasticsearch-kompatibler Abfrage-DSL ausführen. Unterstützt Filterung nach Zeitbereich und Abrufen von Protokollen oder anderen indizierten Dokumenten. Gibt Dokumente mit Index, ID, Quellfeldern und optionalem Relevanzwert zurück.

Agent-Beobachtbarkeit

Hinweis: Agent-Beobachtbarkeits-Tools sind standardmäßig deaktiviert und funktionieren nur in Grafana Cloud. Um sie zu aktivieren, fügen Sie agento11y zu Ihrem --enabled-tools-Flag hinzu.

Unterhaltungen auflisten und durchsuchen: Listen Sie aktuelle LLM-Unterhaltungen auf oder durchsuchen Sie sie mit einem Filterausdruck (Modell, Anbieter, Agent, Status, Fehlertyp, Auswertungsergebnisse und mehr) über einen Zeitraum. Die Suchergebnisse enthalten Fehlerzahlen, Bewertungszusammenfassungen, Auswertungszusammenfassungen und Trace-IDs.
Unterhaltungsdetails abrufen: Rufen Sie eine einzelne Unterhaltung mit allen ihren Generationen ab, einschließlich Prompts und Ausgaben.
Generierungsdetails und Bewertungen abrufen: Rufen Sie eine einzelne Generation anhand ihrer ID sowie ihre Auswertungsbewertungen ab (Bewerter, Bewertungsschlüssel, Wert, bestanden, Erklärung).
Agentenkatalog lesen: Listen Sie die Agenten auf, die Telemetrie senden, rufen Sie eine Agentenversion vollständig ab (vollständiger System-Prompt, jedes Tool mit seinem JSON-Schema und die Modelle, auf denen es lief), durchlaufen Sie den Versionsverlauf eines Agenten und vergleichen Sie die aggregierten Auswertungsbewertungen pro Version. Effektive Versionen sind sha256:-Hashes, die eine Tool-Änderung nie beeinflusst; für einen Agenten, der keine eigene Version meldet, hashen sie den System-Prompt, sodass eine Prompt-Bearbeitung eine neue Version erzeugt. Katalog- und Versionszeilen tragen ein token_estimate, das es wert ist, vor dem Abrufen eines vollständigen Prompts überprüft zu werden.
Bewerter und Vorlagen prüfen: Lesen Sie die Bewerter, von denen eine Bewertung stammt, die Vorlagen, aus denen sie abgeleitet wurden, sowie die Judge-Anbieter und -Modelle, die für LLM-Judge-Bewerter verfügbar sind. Mit aktivierten Schreibwerkzeugen können Sie auch Bewerter erstellen, forken, testen und löschen.
Auswertungsregeln und Guards prüfen: Lesen Sie die asynchronen Auswertungsregeln, die Bewerter an Produktionsdatenverkehr binden, sowie die Guards (Hook-Regeln), die inline ausgeführt werden und warnen oder verweigern können. Mit aktivierten Schreibwerkzeugen können Sie diese auch erstellen, aktualisieren, in der Vorschau anzeigen und löschen. Schreibvorgänge und die nicht persistierenden preview_rule- und test_evaluator-Operationen benötigen die grafana-agento11y-app.eval:write-Berechtigung, die von der Agento11y-Admin-Rolle gewährt wird.
Gespeicherte Unterhaltungen und Sammlungen kuratieren: Lesen Sie die gespeicherten Unterhaltungen (Lesezeichen, die einer Unterhaltung eine stabile ID, einen Namen und Tags geben) und die Sammlungen, die sie gruppieren, einschließlich der Mitgliederanzahl jeder Sammlung und der Sammlungen, die in jeder gespeicherten Unterhaltungszeile eingebettet sind. Mit aktivierten Schreibwerkzeugen können Sie auch eine Unterhaltung mit einem Lesezeichen versehen, Sammlungen erstellen und bearbeiten sowie Mitglieder hinzufügen oder entfernen. Diese Schreibvorgänge benötigen dieselbe grafana-agento11y-app.eval:write-Berechtigung.
Testsuiten lesen und bearbeiten: Listen Sie die versionierten Testsuiten auf, gegen die Offline-Experimente ausgeführt werden, lesen Sie eine mit ihrem vollständigen Versionsverlauf und blättern Sie durch die Testfälle einer Version. Mit aktivierten Schreibwerkzeugen können Sie auch eine Suite erstellen, umbenennen oder neu taggen, eine Entwurfsversion öffnen, veröffentlichen und ihre Testfälle schreiben oder löschen. Eine veröffentlichte Version ist eingefroren, daher bedeutet eine Bearbeitung das Öffnen eines neuen Entwurfs. Diese Schreibvorgänge benötigen grafana-agento11y-app.eval:write.
Offline-Experimente lesen: Listen Sie die Auswertungsläufe über eine Testsuit auf und lesen Sie einen mit seiner Hauptbestehensquote, Kosten und Token-Summen. Bohren Sie sich durch einen Testfallbericht zu Versuchen, ihren Bewertungen mit der Erklärung jedes Judges und ihren Artefakt-Metadaten. Mit aktivierten Schreibwerkzeugen können Sie auch ein Experiment umbenennen oder neu taggen und ein laufendes abbrechen, was grafana-agento11y-app.eval:write erfordert. Experimente werden von SDK-Runnern erstellt, nicht von diesem Tool.

Grafana Assistant

Hinweis: Assistant-Tools sind standardmäßig deaktiviert und erfordern das Grafana Assistant-Plugin (grafana-assistant-app), das auf der Ziel-Grafana-Instanz installiert sein muss. Sie sind auch Schreibwerkzeuge (der Assistent kann den Stack-Zustand verändern), daher werden sie übersprungen, wenn --disable-write gesetzt ist. Um sie zu aktivieren, fügen Sie assistant zu Ihrem --enabled-tools-Flag hinzu.

Assistenten fragen: Senden Sie eine natürliche Sprachaufforderung an Grafana Assistant und warten Sie auf die vollständige Textantwort. Der Assistent kann Tools, Metriken, Protokolle und anderen Stack-Kontext verwenden – breiter als das Auslösen einer einzelnen isolierten Datenquellenabfrage. Geben Sie das zurückgegebene contextId in einem Folgeaufruf zurück, um dieselbe Unterhaltung fortzusetzen. Komplexe Aufgaben können mehrere Minuten dauern; der Aufruf blockiert, bis die Antwort fertig ist oder die Anfrage ein Zeitlimit überschreitet (5 Minuten).

Vorfälle

Vorfälle suchen, erstellen und aktualisieren: Verwalten Sie Vorfälle in Grafana Incident, einschließlich Suchen, Erstellen, Hinzufügen von Aktivitäten und Lesen oder Festlegen benutzerdefinierter Felder.

Alarmierung

Alarmregelinformationen auflisten und abrufen: Zeigen Sie Alarmregeln und ihre Status (auslösend/normal/Fehler usw.) in Grafana an. Unterstützt sowohl Grafana-verwaltete Regeln als auch von Datenquellen verwaltete Regeln aus Prometheus- oder Loki-Datenquellen.
Alarmregeln erstellen und aktualisieren: Erstellen Sie neue Alarmregeln oder ändern Sie bestehende.
Alarmregeln löschen: Entfernen Sie Alarmregeln per UID.
Alarmierungsrouting verwalten: Zeigen Sie Benachrichtigungsrichtlinien, Kontaktpunkte und Zeitintervalle an. Unterstützt sowohl Grafana-verwaltete Kontaktpunkte als auch Empfänger aus externen Alertmanager-Datenquellen (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

Zeitpläne auflisten und verwalten: Zeigen und verwalten Sie Bereitschaftszeitpläne in Grafana OnCall.
Schichtdetails abrufen: Rufen Sie detaillierte Informationen zu bestimmten Bereitschaftsschichten ab.
Aktuelle Bereitschaftsbenutzer abrufen: Sehen Sie, welche Benutzer derzeit für einen Zeitplan im Bereitschaftsdienst sind.
Teams und Benutzer auflisten: Zeigen Sie alle OnCall-Teams und -Benutzer an.
Alarmgruppen auflisten: Zeigen und filtern Sie Alarmgruppen aus Grafana OnCall nach verschiedenen Kriterien, einschließlich Status, Integration, Labels und Zeitraum.
Alarmgruppendetails abrufen: Rufen Sie detaillierte Informationen zu einer bestimmten Alarmgruppe anhand ihrer ID ab.

Admin

Hinweis: Admin-Tools sind standardmäßig deaktiviert. Um sie zu aktivieren, fügen Sie admin in Ihr --enabled-tools-Flag ein.

Teams auflisten: Zeigen Sie alle konfigurierten Teams in Grafana an.
Benutzer auflisten: Zeigen Sie alle Benutzer in einer Organisation in Grafana an.
Alle Rollen auflisten: Listen Sie alle Grafana-Rollen auf, mit einem optionalen Filter für delegierbare Rollen.
Rollendetails abrufen: Rufen Sie Details für eine bestimmte Grafana-Rolle per UID ab.
Zuweisungen für eine Rolle auflisten: Listen Sie alle Benutzer, Teams und Dienstkonten auf, die einer Rolle zugewiesen sind.
Rollen für Benutzer auflisten: Listen Sie alle Rollen auf, die einem oder mehreren Benutzern zugewiesen sind.
Rollen für Teams auflisten: Listen Sie alle Rollen auf, die einem oder mehreren Teams zugewiesen sind.
Berechtigungen für eine Ressource auflisten: Listen Sie alle Berechtigungen auf, die für eine bestimmte Ressource (Dashboard, Datenquelle, Ordner usw.) definiert sind.
Eine Grafana-Ressource beschreiben: Listen Sie verfügbare Berechtigungen und Zuweisungsfähigkeiten für einen Ressourcentyp auf.

Benutzer

Benutzerinformationen: Rufen Sie die aktuelle Grafana-Identität ab – Login, E-Mail, Name, ob es sich um einen Grafana- (Server-) Admin handelt, die aktuelle Organisation und die Organisationen, auf die die Anmeldedaten zugreifen können (mit Rollen). Verwenden Sie dies, um gültige orgId-Werte für Multi-Organisations-Anfragen zu ermitteln.

Navigation

Deeplinks generieren: Erstellen Sie genaue Deeplink-URLs für Grafana-Ressourcen, anstatt sich auf LLM-URL-Raten zu verlassen.
- Dashboard-Links: Generieren Sie direkte Links zu Dashboards mithilfe ihrer UID (z. B. http://localhost:3000/d/dashboard-uid)
- Panel-Links: Erstellen Sie Links zu bestimmten Panels in Dashboards mit dem viewPanel-Parameter (z. B. http://localhost:3000/d/dashboard-uid?viewPanel=5)
- Explore-Links: Generieren Sie Links zu Grafana Explore mit vorkonfigurierten Datenquellen (z. B. http://localhost:3000/explore?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}). Grafana unter 10.2 versteht panes nicht, daher wird das Legacy-Format ?left={...} für diese Versionen ausgegeben.
- Zeitraumunterstützung: Fügen Sie Zeitraumparameter zu Links hinzu (from=now-1h&to=now)
- Benutzerdefinierte Parameter: Fügen Sie zusätzliche Abfrageparameter wie Dashboard-Variablen oder Aktualisierungsintervalle hinzu

Annotationen

Annotationen abrufen: Fragen Sie Annotationen mit Filtern ab. Unterstützt Zeitraum, Dashboard-UID, Tags und Übereinstimmungsmodus.
Annotation erstellen: Erstellen Sie eine neue Annotation auf einem Dashboard oder Panel.
Graphite-Annotation erstellen: Erstellen Sie Annotationen im Graphite-Format (what, when, tags, data).
Annotation aktualisieren: Ersetzen Sie alle Felder einer vorhandenen Annotation (vollständige Aktualisierung).
Annotation patchen: Aktualisieren Sie nur bestimmte Felder einer Annotation (teilweise Aktualisierung).
Annotation löschen: Löschen Sie eine Annotation dauerhaft anhand ihrer ID.
Annotation-Tags abrufen: Listen Sie verfügbare Annotation-Tags mit optionaler Filterung auf.

Snapshots

Snapshots auflisten: Listen Sie Dashboard-Snapshots mit optionalen Abfrage- und Limit-Filtern auf.
Snapshot abrufen: Rufen Sie Snapshot-Metadaten und Dashboard-Nutzdaten anhand des Snapshot-Schlüssels ab.
Snapshot erstellen: Erstellen Sie einen Dashboard-Snapshot aus vollständigen Dashboard-Nutzdaten, mit optionalen Ablauf- und externen Snapshot-Optionen.
Snapshot löschen: Löschen Sie einen Snapshot anhand des Snapshot-Schlüssels.

Rendering

Panel- oder Dashboard-Bild abrufen: Rendern Sie ein Grafana-Dashboard-Panel oder ein vollständiges Dashboard als PNG-Bild. Gibt das Bild als base64-codierte Daten für Berichte, Alarme oder Präsentationen zurück. Unterstützt die Anpassung von Abmessungen, Zeitraum, Design, Skalierung und Dashboard-Variablen. Unterstützt auch das Rendern noch nicht angewendeter Dashboards aus einem Provisioning-Repository-Zweig (z. B. eine Git-Sync-PR-Vorschau) über den optionalen provisioningPreview-Parameter.
- Hinweis: Erfordert, dass der Grafana Image Renderer-Dienst installiert und konfiguriert ist.

Provisioning

Provisioning-Repositorys auflisten: Listen Sie Provisioning-Repositorys auf, die für diese Grafana-Instanz konfiguriert sind (z. B. Git-Sync-Quellen), und geben Sie den Slug jedes Repositorys zusammen mit seiner Quell-URL, seinem Zweig, seinem Pfad, seinem Synchronisierungsstatus und seiner Gesundheit zurück.
Provisioning-Datei validieren: Führen Sie eine Trockenlauf-Anwendung einer Datei aus einem Provisioning-Repository an einem bestimmten Zweig oder Commit durch. Gibt zurück, ob sie akzeptiert würde, die Ressourcenaktion (erstellen/aktualisieren), den Zielressourcentyp und alle strukturierten Validierungsfehler – dieselbe Zulassungsoberfläche, die Grafanas PR-Kommentator verwendet.

Die Liste der Tools ist konfigurierbar, sodass Sie auswählen können, welche Tools Sie dem MCP-Client zur Verfügung stellen möchten. Dies ist nützlich, wenn Sie bestimmte Funktionen nicht verwenden oder nicht zu viel vom Kontextfenster beanspruchen möchten. Um eine Kategorie von Tools zu deaktivieren, verwenden Sie das --disable-<category>-Flag beim Starten des Servers. Um beispielsweise die OnCall-Tools zu deaktivieren, verwenden Sie --disable-oncall, oder um die Navigation-Deeplink-Generierung zu deaktivieren, verwenden Sie --disable-navigation.

RBAC-Berechtigungen

Jedes Tool erfordert spezifische RBAC-Berechtigungen, um ordnungsgemäß zu funktionieren. Wenn Sie ein Dienstkonto für den MCP-Server erstellen, stellen Sie sicher, dass es die erforderlichen Berechtigungen basierend auf den Tools hat, die Sie verwenden möchten. Die aufgeführten Berechtigungen sind die mindestens erforderlichen Aktionen – Sie benötigen möglicherweise auch geeignete Bereiche (z. B. datasources:*, dashboards:*, folders:*), je nach Anwendungsfall.

Tipp: Wenn Sie mit Grafana RBAC nicht vertraut sind oder eine schnellere, einfachere Einrichtung anstelle der Konfiguration vieler granularer Bereiche wünschen, können Sie dem Dienstkonto eine integrierte Rolle wie Editor zuweisen. Die Editor-Rolle gewährt breiten Lese-/Schreibzugriff, der die meisten MCP-Serveroperationen ermöglicht; sie ist weniger granular (und daher weniger restriktiv) als manuell angewendete Bereiche, verwenden Sie sie also nur, wenn Bequemlichkeit wichtiger ist als strenger Zugriff mit geringsten Rechten.

Hinweis: Grafana Incident-Tools verwenden grundlegende Grafana-Rollen anstelle von fein abgestuften RBAC-Berechtigungen:

Viewer-Rolle: Erforderlich für schreibgeschützte Operationen (Vorfälle auflisten, Untersuchungen abrufen)
Editor-Rolle: Erforderlich für Schreiboperationen (Vorfälle erstellen, Untersuchungen ändern)

Weitere Informationen zu Grafana RBAC finden Sie in der offiziellen Dokumentation.

RBAC-Bereiche

Bereiche definieren die spezifischen Ressourcen, auf die Berechtigungen angewendet werden. Jede Aktion erfordert sowohl die geeignete Berechtigungs- als auch Bereichskombination.

Häufige Bereichsmuster:

Breiter 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 spezifische 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 Dashboard mit UID abc123
- folders:uid:xyz789 - Zugriff nur auf Ordner mit UID xyz789
- teams:id:5 - Zugriff nur auf Team mit ID 5
- global.users:id:123 - Zugriff nur auf Benutzer mit ID 123

Beispiele:

Voller MCP-Serverzugriff: Erteilen Sie breite 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 Datenquellenzugriff: Nur bestimmte Prometheus- und Loki-Instanzen abfragen

datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)

Dashboard-spezifischer Zugriff: Nur bestimmte Dashboards lesen

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

Tools

Tool	Kategorie	Beschreibung	Erforderliche RBAC-Berechtigungen	Erforderliche Scopes
`list_teams`	Admin	Alle Teams auflisten	`teams:read`	`teams:*` oder `teams:id:1`
`list_users_by_org`	Admin	Alle Benutzer in einer Organisation auflisten	`users:read`	`global.users:*` oder `global.users:id:123`
`list_all_roles`	Admin	Alle Grafana-Rollen auflisten	`roles:read`	`roles:*`
`get_role_details`	Admin	Details für eine Grafana-Rolle abrufen	`roles:read`	`roles:uid:editor`
`get_role_assignments`	Admin	Zuweisungen für eine Rolle auflisten	`roles:read`	`roles:uid:editor`
`list_user_roles`	Admin	Rollen für Benutzer auflisten	`roles:read`	`global.users:id:123`
`list_team_roles`	Admin	Rollen für Teams auflisten	`roles:read`	`teams:id:7`
`get_resource_permissions`	Admin	Berechtigungen für eine Ressource auflisten	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	Admin	Einen Grafana-Ressourcentyp beschreiben	`permissions:read`	`dashboards:*`
`user_info`	Benutzer	Aktuelle Identität, Fähigkeiten und zugängliche Organisationen	Keine (angemeldeter Benutzer)	—
`search_dashboards`	Suche	Dashboards nach Abfrage, Ordner-UID, Tag oder markiert suchen	`dashboards:read`	`dashboards:*` oder `dashboards:uid:abc123`
`get_dashboard_by_uid`	Dashboard	Ein Dashboard per UID abrufen, optional eine gespeicherte Version	`dashboards:read`	`dashboards:uid:abc123`
`list_dashboard_versions`	Dashboard	Gespeicherte Versionen eines Dashboards auflisten (Version, Autor, Zeit, Nachricht)	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	Dashboard	Ein Dashboard aktualisieren oder neu erstellen	`dashboards:create`, `dashboards:write`	`dashboards:`, `folders:` oder `folders:uid:xyz789`
`get_dashboard_panel_queries`	Dashboard	Panel-Titel, Abfragen, Datenquellen-UID und -Typ aus einem Dashboard abrufen	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	RunPanelQuery*	Eine oder mehrere Dashboard-Panel-Abfragen ausführen	`dashboards:read`, `datasources:query`	`dashboards:uid:`, `datasources:uid:`
`get_dashboard_property`	Dashboard	Bestimmte Teile eines Dashboards mithilfe von JSONPath-Ausdrücken extrahieren	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	Dashboard	Eine kompakte Zusammenfassung eines Dashboards ohne vollständiges JSON abrufen	`dashboards:read`	`dashboards:uid:abc123`
`list_datasources`	Datenquellen	Datenquellen auflisten	`datasources:read`	`datasources:*`
`get_datasource`	Datenquellen	Eine Datenquelle per UID oder Name abrufen	`datasources:read`	`datasources:uid:prometheus-uid`
`get_query_examples`	Beispiele*	Beispielabfragen für einen Datenquellentyp abrufen	`datasources:read`	`datasources:*`
`query_prometheus`	Prometheus	Eine Abfrage gegen eine Prometheus-Datenquelle ausführen	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_metadata`	Prometheus	Metadaten von Metriken auflisten	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	Verfügbare Metriknamen auflisten	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	Labelnamen auflisten, die einem Selektor entsprechen	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	Werte für ein bestimmtes Label auflisten	`datasources:query`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	Histogramm-Perzentilwerte berechnen	`datasources:query`	`datasources:uid:prometheus-uid`
`list_incidents`	Incident	Vorfälle in Grafana Incident auflisten, optional mit ihren benutzerdefinierten Feldwerten	Viewer-Rolle	N/V
`create_incident`	Incident	Einen Vorfall in Grafana Incident erstellen, optional mit benutzerdefinierten Feldern	Editor-Rolle	N/V
`add_activity_to_incident`	Incident	Ein Aktivitätselement zu einem Vorfall in Grafana Incident hinzufügen	Editor-Rolle	N/V
`update_incident`	Incident	Einen Vorfall in Grafana Incident aktualisieren (Status, Schweregrad, Titel oder benutzerdefinierte Felder)	Editor-Rolle	N/V
`get_incident`	Incident	Einen einzelnen Vorfall per ID abrufen, einschließlich seiner benutzerdefinierten Felder	Viewer-Rolle	N/V
`list_incident_custom_fields`	Incident	Die für Vorfälle konfigurierten benutzerdefinierten Felder mit ihren Typen und Auswahloptionen auflisten	Viewer-Rolle	N/V
`query_loki_logs`	Loki	Protokolle mithilfe von LogQL abfragen und abrufen (entweder Protokoll- oder Metrikabfragen)	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	Alle verfügbaren Labelnamen in Protokollen auflisten	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	Werte für ein bestimmtes Protokoll-Label auflisten	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	Statistiken über Protokoll-Streams abrufen	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	Erkannte Protokollmuster abfragen, um gemeinsame Strukturen zu identifizieren	`datasources:query`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	Eine Loki-Labelstrategie prüfen (live oder statisch) und optional die Abfrageleistung diagnostizieren	`datasources:query`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Konfiguration	Ein Alloy `loki.process`-Snippet generieren, das genehmigte Labels durchsetzt	N/V	N/V
`query_influxdb`	InfluxDB	InfluxDB mit InfluxQL (v1) oder Flux (v2) abfragen	`datasources:query`	`datasources:uid:influxdb-uid`
`list_sql_databases`	SQL*	Datenbanken, Schemas oder Kataloge aus einer SQL-Datenquelle auflisten	`datasources:query`	`datasources:uid:*`
`list_sql_tables`	SQL*	Tabellen in einer SQL-Datenquelle auflisten	`datasources:query`	`datasources:uid:*`
`describe_sql_table`	SQL*	Spaltenschema für eine Tabelle abrufen	`datasources:query`	`datasources:uid:*`
`query_sql`	SQL*	SQL-Abfragen mit Makro-Substitution ausführen	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	Verfügbare AWS CloudWatch-Namespaces auflisten	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	Metriken in einem Namespace auflisten	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	Dimensionen für eine Metrik auflisten	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimension_values`	CloudWatch*	Werte für einen Dimensionsschlüssel auflisten	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	CloudWatch-Metrikabfragen ausführen	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_projects`	Cloud Logging*	GCP-Projekte auflisten, die von einer Google Cloud Logging-Datenquelle lesbar sind	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_buckets`	Cloud Logging*	Log-Buckets in einem GCP-Projekt auflisten	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_views`	Cloud Logging*	Log-Ansichten in einem Log-Bucket auflisten	`datasources:query`	`datasources:uid:*`
`query_cloud_logging`	Cloud Logging*	Logs mit der Cloud Logging-Abfragesprache abfragen	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	Elasticsearch oder OpenSearch mit Lucene-Syntax oder Query DSL abfragen	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	Quickwit mit Lucene-Syntax oder Query DSL abfragen	`datasources:query`	`datasources:uid:quickwit-uid`
`alerting_rules_read`	Alerting	Alarmregeln auflisten und prüfen (auflisten, abrufen, Versionen)	`alert.rules:read`	`folders:*` oder `folders:uid:alerts-folder`
`alerting_rules_write`	Alerting	Alarmregeln erstellen, aktualisieren und löschen	`alert.rules:read` + `alert.rules:write`	`folders:*` oder `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	Benachrichtigungsrichtlinien, Kontaktpunkte und Zeitintervalle verwalten	`alert.notifications:read`	Globaler Geltungsbereich
`alerting_routing_write`	Alerting	Von Grafana verwaltete Kontaktpunkte erstellen	`alert.notifications.provisioning:write`	Globaler Geltungsbereich
`alerting_silences_read`	Alerting	Alarm-Stummschaltungen auflisten und prüfen (auflisten, abrufen)	`alert.instances:read`	Globaler Geltungsbereich
`alerting_silences_write`	Alerting	Alarm-Stummschaltungen erstellen, aktualisieren und ablaufen lassen	`alert.instances:read` + `alert.instances:write`	Globaler Geltungsbereich
`list_oncall_schedules`	OnCall	Zeitpläne aus Grafana OnCall auflisten	`grafana-oncall-app.schedules:read`	Plugin-spezifische Geltungsbereiche
`get_oncall_shift`	OnCall	Details für eine bestimmte OnCall-Schicht abrufen	`grafana-oncall-app.schedules:read`	Plugin-spezifische Geltungsbereiche
`get_current_oncall_users`	OnCall	Benutzer abrufen, die derzeit für einen bestimmten Zeitplan im Bereitschaftsdienst sind	`grafana-oncall-app.schedules:read`	Plugin-spezifische Geltungsbereiche
`list_oncall_teams`	OnCall	Teams aus Grafana OnCall auflisten	`grafana-oncall-app.user-settings:read`	Plugin-spezifische Geltungsbereiche
`list_oncall_users`	OnCall	Benutzer aus Grafana OnCall auflisten	`grafana-oncall-app.user-settings:read`	Plugin-spezifische Geltungsbereiche
`list_alert_groups`	OnCall	Alarmgruppen aus Grafana OnCall mit Filteroptionen auflisten	`grafana-oncall-app.alert-groups:read`	Plugin-spezifische Geltungsbereiche
`get_alert_group`	OnCall	Eine bestimmte Alarmgruppe aus Grafana OnCall anhand ihrer ID abrufen	`grafana-oncall-app.alert-groups:read`	Plugin-spezifische Geltungsbereiche
`update_alert_group`	OnCall	Eine Alarmgruppe bestätigen, Bestätigung aufheben, auflösen oder Auflösung aufheben	`grafana-oncall-app.alert-groups:write` (und `:read`)	Plugin-spezifische Geltungsbereiche
`list_pyroscope_label_names`	Pyroscope	Labelnamen auflisten, die einem Selektor entsprechen	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	Labelwerte auflisten, die einem Selektor für einen Labelnamen entsprechen	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	Verfügbare Profiltypen auflisten	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	Profile, Metriken oder beides aus Pyroscope abfragen	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	Assertions-Zusammenfassung für eine bestimmte Entität abrufen	Plugin-spezifische Berechtigungen	Plugin-spezifische Geltungsbereiche
`agento11y_manage_conversations`	Agent Observability*	LLM-Konversationen aus Grafana Agent Observability auflisten, durchsuchen und abrufen	`grafana-agento11y-app.conversations:read`	N/A
`agento11y_manage_generations`	Agent Observability*	LLM-Generierungsdetails und Bewertungsergebnisse aus Grafana Agent Observability abrufen	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_agents`	Agent Observability*	Den Agent-Katalog lesen: Agenten auflisten, eine Agentenversion vollständig abrufen, Versionsverlauf auflisten und Bewertungsaggregate pro Version abrufen	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_evaluators`	Agent Observability*	Bewerter, Bewertervorlagen und den Bewerterkatalog verwalten (auflisten, abrufen, upsert, forken, testen, löschen)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` für Mutationen und Tests	N/A
`agento11y_manage_eval_rules`	Agent Observability*	Bewertungsregeln und Schutzmechanismen verwalten (auflisten, abrufen, erstellen, aktualisieren, Vorschau, löschen)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` für Mutationen und Vorschauen	N/A
`agento11y_manage_eval_collections`	Agent Observability*	Gespeicherte Konversationen und die Sammlungen, die sie gruppieren, verwalten (auflisten, abrufen, speichern, erstellen, aktualisieren, löschen, Mitglieder hinzufügen und entfernen)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` für Mutationen	N/A
`agento11y_manage_experiments`	Agent Observability*	Offline-Experimente, ihre Versuche, Bewertungen, Artefakt-Metadaten und Filterfacetten lesen; ein Experiment aktualisieren und abbrechen	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` für Mutationen	N/A
`agento11y_manage_test_suites`	Agent Observability*	Die Testsuiten verwalten, gegen die Offline-Experimente laufen, ihre Versionen und ihre Testfälle (auflisten, abrufen, erstellen, aktualisieren, Entwurf, veröffentlichen, upsert, löschen)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` für Mutationen	N/A
`ask_assistant`	Assistant*	Senden Sie eine Eingabeaufforderung an den Grafana-Assistenten und erhalten Sie die vollständige Textantwort (mehrteilig über `contextId`)	Plugin-spezifische Berechtigungen	Plugin-spezifische Bereiche
`generate_deeplink`	Navigation	Generieren Sie genaue Deeplink-URLs für Grafana-Ressourcen	Keine (schreibgeschützte URL-Generierung)	N/V
`get_annotations`	Anmerkungen	Anmerkungen mit Filtern abrufen	`annotations:read`	`annotations:*` oder `annotations:id:123`
`create_annotation`	Anmerkungen	Eine neue Anmerkung erstellen (Standard- oder Graphite-Format)	`annotations:write`	`annotations:*`
`update_annotation`	Anmerkungen	Bestimmte Felder einer Anmerkung aktualisieren (teilweise Aktualisierung)	`annotations:write`	`annotations:*`
`delete_annotation`	Anmerkungen	Eine Anmerkung anhand der ID löschen	`annotations:delete`	`annotations:*`
`get_annotation_tags`	Anmerkungen	Anmerkungstags mit optionaler Filterung auflisten	`annotations:read`	`annotations:*`
`list_snapshots`	Snapshot	Dashboard-Snapshots mit optionalen Abfrage- und Limit-Filtern auflisten	`dashboards:read`	`dashboards:*` oder `dashboards:uid:abc123`
`get_snapshot`	Snapshot	Snapshot-Metadaten und Dashboard-Payload anhand des Snapshot-Schlüssels abrufen	`dashboards:read`	`dashboards:*` oder `dashboards:uid:abc123`
`create_snapshot`	Snapshot	Einen Dashboard-Snapshot aus einer vollständigen Dashboard-Payload erstellen	`dashboards:write`	`dashboards:*` oder `dashboards:uid:abc123`
`delete_snapshot`	Snapshot	Einen Dashboard-Snapshot anhand des Snapshot-Schlüssels löschen	`dashboards:write`	`dashboards:*` oder `dashboards:uid:abc123`
`get_panel_image`	Rendering	Ein gespeichertes Dashboard oder Panel – oder eine Provisioning-Vorschau aus einem Repository-Zweig – als PNG-Bild rendern	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	Provisioning	Provisioning-Repositorys auflisten (z. B. git-sync-Quellen) mit Quell-URL, Zweig, Synchronisierungsstatus und Zustand	`provisioning.repositories:read`	N/V
`validate_provisioning_file`	Provisioning	Eine Datei aus einem Provisioning-Repository im Trockenlauf anwenden und Admissions-Validierungsfehler melden	`provisioning.repositories:read`	N/V
`search_docs`	Dokumentation	Grafana-Dokumentation durchsuchen oder Produktgruppen auflisten (Abfrage weglassen, um Produkte aufzulisten)	Keine (öffentliche grafana.com/docs)	N/V
`get_doc`	Dokumentation	Eine Dokumentationsseite abrufen; setzen Sie outline_only für Überschriften oder section für begrenzten Abruf	Keine (öffentliche grafana.com/docs)	N/V
* Standardmäßig deaktiviert. Füge Kategorie zu `--enabled-tools` hinzu, um sie zu aktivieren.

Das get_tempo_trace-Tool zeigt einen interaktiven Trace-Viewer in kompatiblen MCP-Hosts an, wenn Tempo-Abfragetools aktiviert sind. Die vorhandene Textausgabe bleibt verfügbar. Siehe MCP-Apps für Einrichtung und Bibliothekseinbettung.

CLI-Flags-Referenz

Die mcp-grafana-Binärdatei unterstützt verschiedene Befehlszeilen-Flags für die 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 auf der Server-Root-Ebene bereitgestellt, nicht unter diesem Präfix – sie sind nur interne Endpunkte für Probes und Scraper, und sie vom Anwendungspräfix fernzuhalten erleichtert die Bereitstellung der API über einen Reverse-Proxy, ohne sie ebenfalls offenzulegen
--endpoint-path: Endpunktpfad für den streamable-http-Server, angehängt an --base-path – Standard: /mcp
--server-name: Servername, der im MCP-Handshake und in OTel service.name verwendet wird – Standard: mcp-grafana. Überschreibt die Umgebungsvariable GRAFANA_MCP_SERVER_NAME
--instructions-append: Text, der den Serveranweisungen hinzugefügt wird, die MCP-Clients bei der Initialisierung zurückgegeben werden, sodass jeder verbundene Agent ihn sieht

[!NOTE] Über SSE erreichen Pro-Request-Header keine Tool-Aufrufe: 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 Umgebungsanmeldeinformationen des Servers, und X-Grafana-URL-Überschreibungen funktionieren nicht. Verwenden Sie streamable-http, wenn jeder Aufrufer seine eigene Grafana-URL, Anmeldeinformationen oder Organisation benötigt.

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

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

--allowed-hosts: Kommagetrennte Zulassungsliste von Host-Headerwerten. Standardmäßig Loopback-Varianten von --address (z. B. localhost:8000,127.0.0.1:8000,[::1]:8000). Ein Wert, der zu leer geparst wird (nicht gesetzt, ,, , usw.), fällt ebenfalls auf die Standardwerte zurück, sodass ein Tippfehler die Prüfung nicht stillschweigend deaktivieren kann. Anfragen mit einem Host-Header außerhalb der Zulassungsliste werden mit 403 abgelehnt. Übergeben Sie *, um die Host-Validierung zu deaktivieren – nur sicher, wenn ein vertrauenswürdiger Reverse-Proxy Host validiert. K8s-httpGet-Probes und externe /metrics-Scrapes benötigen entweder einen expliziten Hostnamen in dieser Liste, *, eine tcpSocket-Probe oder einen separaten Port (--healthz-address / --metrics-address).
--allowed-origins: Kommagetrennte Zulassungsliste von Origin-Headerwerten. Standardmäßig leer – jede Anfrage, die einen Origin-Header trägt, wird abgelehnt (Browser senden immer einen für Cross-Origin-Anfragen, und kein Browser sollte diesen Server direkt aufrufen). Setzen Sie eine explizite Liste, um browserbasierte Clients zu erlauben, oder *, um die Prüfung zu deaktivieren.
--allow-grafana-url-override: X-Grafana-URL-Auswahl 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 kommagetrennte exakte Grafana-Basis-URL-Zulassungsliste für URL-Überschreibungen. Fällt auf GRAFANA_ALLOWED_URLS zurück. Erfordert --allow-grafana-url-override; ein explizites leeres Flag deaktiviert eine geerbte Liste.

Aufrufer-Authentifizierung (nur SSE / streamable-http):

Optional können MCP-Clients verpflichtet werden, sich gegenüber dem Server zu authentifizieren. Dies ist getrennt von den Anmeldeinformationen, die der Server verwendet, um Grafana zu erreichen. Stdio ist 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. Bevorzugen Sie die Umgebungsvariable, damit das Geheimnis nicht in den Prozessargumenten sichtbar ist.

Die Aufrufer-Authentifizierung wird nur erzwungen, wenn --server-auth-token gesetzt ist. Wenn sie nicht gesetzt ist und der Server eine Nicht-Loopback-Adresse bindet, startet der Server, protokolliert jedoch einen Sicherheitsfehler – ausgegeben auf der error-Protokollebene, sodass er nicht durch --log-level verborgen wird (Loopback und Stdio sind nicht betroffen); eine zukünftige Hauptversion wird dies zu einem Startfehler machen. Verwenden Sie TLS (oder TLS-Terminierung), wann immer Aufrufer-Authentifizierung auf einer Nicht-Loopback-Adresse aktiviert ist. Wenn Aufrufer-Authentifizierung aktiviert ist, wird der validierte Authorization-Header 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):

[!WARNUNG] URL-Überschreibungen ermöglichen es MCP-Aufrufern, ausgehende HTTP(S)-Ziele auszuwählen. Eine Zulassungsliste begrenzt URLs, authentifiziert jedoch keine Aufrufer oder bindet Token an Ziele.

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

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

Setzen Sie 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, setzen Sie auch GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana (oder --allowed-grafana-urls).

Senden Sie diese Header bei jeder MCP-Anfrage, die ein Ziel auswählt:

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

Wenn --server-auth-token konfiguriert ist, senden Sie auch Authorization: Bearer <MCP caller token>. Dies authentifiziert gegenüber dem MCP-Server und ist getrennt von X-Grafana-Service-Account-Token, das für die ausgewählte Grafana-Instanz bestimmt ist. Ihr Proxy kann für jede Instanz ein anderes Grafana-Token senden; der Server teilt niemals ein konfiguriertes Token über sie hinweg. Der veraltete X-Grafana-API-Key-Header funktioniert ebenfalls. Eine URL-Header ohne Anfrage-Grafana-Token wird abgelehnt. Verwenden Sie TLS für eingehende Anfragen, da sie Token tragen.

Die Zulassungsliste gleicht exakte Basis-URLs ab, einschließlich Schema, Port und Pfad; Platzhalter werden nicht unterstützt. Grafana-Authentifizierung ist keine SSRF-Abwehr.

Für eine ausgewählte URL verwendet der Server nicht GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, GRAFANA_API_KEY, Umgebungs-Basisauthentifizierung, GRAFANA_EXTRA_HEADERS oder Client-Zertifikate. Die TLS-Verifizierung bleibt aktiviert, selbst wenn --tls-skip-verify gesetzt ist; eine konfigurierte CA-Datei gilt weiterhin. Header, die explizit von 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 GRAFANA_URL- und Umgebungs-Anmeldeinformationsverhalten. Diese Option gilt nur für streamable HTTP. Sie funktioniert nicht über SSE, das keine Pro-Request-Header an Tool-Aufrufe weitergibt; eine ausgewählte URL wird dort ohne das Token des Aufrufers verwendet, sodass die Aufrufe fehlschlagen.

Debug und Protokollierung:

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

Grafana-Client-Optionen:

--grafana-timeout: Zeitlimit für Anfragen des Grafana-Clients. Akzeptiert Go-Dauerstrings (z. B. 10s, 500ms) – Standard: 10s
--allow-cross-origin-redirects: Ausgehenden Grafana-Clients erlauben, Weiterleitungen zu einem anderen Schema, Host oder Port zu folgen. Standardmäßig false; GRAFANA_ALLOW_CROSS_ORIGIN_REDIRECTS ist der Umgebungs-Fallback. Die Aktivierung kann Grafana-Anmeldeinformationen an das Weiterleitungsziel senden. Vom Anfrage ausgewählte Grafana-URLs bleiben auf ihr ausgewähltes Ziel fixiert.
--include-args-in-spans: Tool-Aufrufargumente in OpenTelemetry-Spans einschließen. Nur in Nicht-Produktionsumgebungen aktivieren oder wenn bekannt ist, dass Argumente keine PII enthalten – Standard: false

Beobachtbarkeit:

--metrics: Prometheus-Metriken-Endpunkt unter /metrics aktivieren
--metrics-address: Separate Adresse für den Metriken-Server (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. Teilt einen Listener mit --metrics-address, wenn die beiden Adressen übereinstimmen. Seiten-Listener überspringen die Host/Origin-Validierung.
--slow-request-threshold: Ein Ereignis protokollieren, wenn eine MCP-Anfrage (Tool-Aufruf, Liste, Ressourcenlesen usw.) länger als diese Dauer dauert. Akzeptiert Go-Dauerstrings (z. B. 500ms, 5s). Standard 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: Berichterstattung anonymer Nutzungsstatistiken: enabled, disabled oder log (den Bericht, der gesendet würde, auf stderr ausgeben und nichts senden). Überschreibt die GRAFANA_USAGE_STATS-Umgebungsvariable, die wiederum DO_NOT_TRACK überschreibt; jeder nicht erkannte Wert deaktiviert die Berichterstattung. Siehe den Abschnitt Anonyme Nutzungsstatistiken. Tool-Konfiguration:
--enabled-tools: Kommagetrennte Liste der aktivierten Kategorien – Standard: alle Kategorien außer admin, agento11y, assistant, athena, clickhouse, cloudlogging, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery und snowflake. Um deaktivierte Kategorien zu aktivieren, fügen Sie sie zur Liste hinzu (z. B. "search,datasource,...,snowflake")
--max-loki-log-limit: Maximale Anzahl von Logzeilen, die pro query_loki_logs-Aufruf zurückgegeben werden – Standard: 100. Hinweis: Setzen Sie dies mindestens 1 unter Lokis serverseitigem max_entries_limit_per_query, um die Erkennung von Abschneidungen zu ermöglichen (das Tool fordert intern limit+1 an, um zu erkennen, ob weitere Daten vorhanden sind).
--loki-guardrail-mode: Loki-Abfragekosten-Schutzmechanismus für query_loki_logs – Standard: off. Loki erzwingt max_query_bytes_read bei Log-Abfragen ohne Zeilenfilter nicht, sodass ein breiter Selektor über einen weiten Bereich Terabytes scannen kann; der Schutzmechanismus erfordert einen selektiven Stream-Selektor, begrenzt den effektiven Zeitbereich (einschließlich Range-Vector-Dauern wie [30d]) und prüft vorab die Byte-Schätzung von Lokis Index/Statistik, bevor die Abfrage ausgeführt wird. shadow protokolliert Abfragen, die blockiert würden, lässt sie aber laufen (der Index/Statistik-Roundtrip wird trotzdem bezahlt); enforce lehnt sie mit Umschreibungsanleitungen ab, auf die das LLM reagieren kann. Bei VictoriaLogs gilt der Schutzmechanismus nur für Selektor-förmige ({...}) Abfragen – wenn kein Selektor geparst wird (die normale Form ohne geschweifte Klammern in LogsQL), wird die Abfrage vollständig durchgelassen, und die Byte-Budget-Prüfung findet nie Anwendung (keine kostengünstige Index-Schätzung). Env-Fallback: GRAFANA_LOKI_GUARDRAIL_MODE.
--loki-guardrail-max-bytes: Maximale Bytes, die ein einzelner query_loki_logs-Aufruf scannen darf, geschätzt über Lokis Index/Statistik-API – Standard: 107374182400 (100 GiB). 0 deaktiviert die Byte-Budget-Prüfung. Env-Fallback: GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.
--loki-guardrail-max-range: Maximaler effektiver Zeitbereich für einen einzelnen query_loki_logs-Aufruf, einschließlich Range-Vector-Dauern – Standard: 24h. Akzeptiert Go-Dauerstrings. 0 deaktiviert die Bereichsprüfung. Env-Fallback: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.
--loki-enforced-matchers: LogQL-Label-Matcher, die per UND 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 Loki-Abfragedurchsetzung.
--loki-label-enumeration-fallback: Was die Label-Enumeration-Tools tun, wenn negative erzwungene Matcher sie nicht eingrenzen können: reject (Standard) oder unfiltered. Siehe Loki-Abfragedurchsetzung.
--disable-search: Suchtools deaktivieren
--disable-datasource: Datenquellen-Tools deaktivieren
--disable-incident: Incident-Tools deaktivieren
--disable-prometheus: Prometheus-Tools deaktivieren
--disable-write: Schreib-Tools deaktivieren (Erstellungs-/Aktualisierungsvorgänge)
--disable-query: Abfrage-Tools deaktivieren (Tools, die eine Abfrage gegen eine Datenquelle ausführen); Metadaten- und Erkennungstools bleiben verfügbar
--enable-query: Die Raw-SQL-Abfragetools (query_sql, query_influxdb) auch unter --disable-write registriert lassen. Äquivalent zu --enable-write-tools=query_sql,query_influxdb; als Kurzform für diesen häufigen Fall beibehalten.
--enable-write-tools: Kommagetrennte Liste einzelner Toolnamen, die auch unter --disable-write registriert bleiben, für Tools, deren Schreibverhalten begrenzt genug ist, um unabhängig wieder aktiviert zu werden. Hat keine Wirkung auf ein Tool, dessen gesamte Kategorie deaktiviert ist.
--disable-loki: Loki-Tools deaktivieren
--disable-elasticsearch: Elasticsearch- und OpenSearch-Tools deaktivieren
--disable-quickwit: Quickwit-Tools deaktivieren
--disable-influxdb: InfluxDB-Tools deaktivieren
--disable-alerting: Alerting-Tools 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: Navigations-Tools 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-examples: Abfragebeispiel-Tools deaktivieren
--disable-sql: SQL-Datenquellen-Tools deaktivieren (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). Aliase --disable-clickhouse, --disable-snowflake, --disable-athena funktionieren ebenfalls.
--disable-runpanelquery: Panel-Abfrage-Tools deaktivieren
--disable-graphite: Graphite-Tools deaktivieren
--disable-provisioning: Provisioning-Tools deaktivieren
--disable-agento11y: Agent-Observability-Tools deaktivieren
--disable-assistant: Grafana-Assistant-Tools deaktivieren
--disable-docs: Dokumentations-Tools deaktivieren

Nur-Lese-Modus

Das --disable-write-Flag bietet eine Möglichkeit, den MCP-Server im Nur-Lese-Modus auszuführen und so alle Schreibvorgänge in Ihrer Grafana-Instanz zu verhindern. Dies ist nützlich für Szenarien, in denen Sie sicheren, schreibgeschützten Zugriff bereitstellen möchten, wie zum Beispiel:

Verwendung von Servicekonten mit eingeschränkten Nur-Lese-Berechtigungen
Bereitstellung von Beobachtbarkeitsdaten für KI-Assistenten ohne Änderungsmöglichkeiten
Ausführung in Produktionsumgebungen, in denen Schreibzugriff eingeschränkt sein sollte
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

Alerting-Tools:

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

OnCall-Tools:

update_alert_group

Annotations-Tools:

create_annotation
update_annotation
delete_annotation

Snapshot-Tools:

create_snapshot
delete_snapshot

Raw-SQL-Abfragetools:

Diese führen jede Abfrage aus, die Sie ihnen geben, ohne sie zu prüfen, sodass sie schreiben können, wenn die Datenquellen-Anmeldeinformationen dies zulassen – query_sql führt ein DROP TABLE aus, query_influxdb führt ein DELETE aus. Der Nur-Lese-Modus entfernt sie daher. Übergeben Sie --enable-query, um sie zu behalten, wenn bekannt ist, dass die Datenquellen-Anmeldeinformationen schreibgeschützt sind.

query_sql
query_influxdb

Agent-Observability-Tools:

agento11y_manage_evaluators (Upsert-, Lösch-, Fork-, Test-Evaluator-Vorgänge)
agento11y_manage_eval_rules (Erstellungs-, Aktualisierungs-, Lösch-, Vorschau-Regel- und Guard-Vorgänge)
agento11y_manage_eval_collections (Speichern und Löschen gespeicherter Unterhaltungen; Erstellen, Aktualisieren, Löschen von Sammlungen; Hinzufügen und Entfernen von Sammlungsmitgliedern)
agento11y_manage_experiments (Aktualisierungs- und Abbruch-Experiment-Vorgänge)
agento11y_manage_test_suites (Erstellen und Aktualisieren von Testsuiten; Erstellen und Veröffentlichen von Versionen; Upsert und Löschen von Testfällen)

Alle Lesevorgänge bleiben verfügbar, sodass Sie Dashboards abfragen, PromQL/LogQL-Abfragen ausführen, Ressourcen auflisten und Daten abrufen können. Die Abfragesprachen, die kein Schreiben ausdrücken können – PromQL, LogQL, TraceQL, die Elasticsearch-DSL, Graphite, CloudWatch – behalten ihre Abfragetools im Nur-Lese-Modus; nur die oben aufgeführten Raw-SQL-Tools werden entfernt.

Abfragefreier Modus

Das --disable-query-Flag entfernt jedes Tool, das eine Abfrage gegen eine Datenquelle ausführt, während die Metadaten- und Erkennungstools an Ort und Stelle bleiben. Dies ist nützlich, wenn Sie einen Assistenten möchten, der erkunden kann, was existiert – Datenquellen, Dashboards, Metriknamen, Labels, Tabellenschemata – ohne potenziell teure oder datenpreisgebende Abfragen auszuführen, beispielsweise wenn das Servicekonto über datasources:read, aber nicht über datasources:query verfügt.

Es ist die stärkste der drei Abfrageeinstellungen und gewinnt über --enable-query:

Flags	Sichere Abfragetools (`query_prometheus`, `query_loki_logs`, `run_panel_query`, …)	Raw-SQL-Abfragetools (`query_sql`, `query_influxdb`)
(keine)	registriert	registriert
`--disable-write`	registriert	nicht registriert
`--disable-write --enable-query`	registriert	registriert
`--disable-query`	nicht registriert	nicht registriert
`--disable-query --enable-query`	nicht registriert	nicht registriert

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

Prometheus-Tools:

query_prometheus
query_prometheus_histogram

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 Stream-, Chunk- und Byte-Zählungen zurück, anstatt Log-Inhalte.

Elasticsearch/OpenSearch- und Quickwit-Tools:

query_elasticsearch
query_quickwit

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

query_influxdb

SQL-Datenquellen-Tools (auch durch --disable-write entfernt, siehe oben):

query_sql

Graphite-Tools:

query_graphite
query_graphite_density

CloudWatch-Tools:

query_cloudwatch

Google Cloud Logging-Tools:

query_cloud_logging

Pyroscope-Tools:

query_pyroscope

Panel-Abfrage-Tools:

run_panel_query

Die Kategorien elasticsearch, quickwit, influxdb und runpanelquery enthalten nichts anderes, sodass sie keine Tools registrieren, wenn Abfragen deaktiviert sind. Die verwandten Tools in jeder anderen Kategorie – list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects und so weiter – bleiben verfügbar.

Beachten Sie, dass --disable-query die Abfragetools und den grafana_api_request-POST-zu-/api/ds/query-Pfad steuert, aber nicht jede Route zu einer Datenquelle überwacht. Im Nur-Lese-Modus erlaubt grafana_api_request POST zu /api/ds/query nur, wenn Abfragetools aktiviert sind (gleiche Sperre wie bei den Raw-SQL-Tools – blockiert durch --disable-write, es sei denn, --enable-query überschreibt). get_panel_image, das ein Panel serverseitig rendert, ist nicht betroffen.

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

--tls-cert-file: Pfad zur TLS-Zertifikatsdatei für die Client-Authentifizierung
--tls-key-file: Pfad zur TLS-Private-Key-Datei für die Client-Authentifizierung
--tls-ca-file: Pfad zur TLS-CA-Zertifikatsdatei für die Serververifizierung
--tls-skip-verify: TLS-Zertifikatsprüfung überspringen (unsicher)

Server-TLS-Konfiguration (nur streamable-http-Transport):

--server.tls-cert-file: Pfad zur TLS-Zertifikatsdatei für Server-HTTPS
--server.tls-key-file: Pfad zur TLS-Private-Key-Datei für Server-HTTPS

Verwendung

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

Wenn Sie die Authentifizierung über Servicekonto-Token verwenden, erstellen Sie ein Servicekonto in Grafana mit ausreichenden Berechtigungen, um die gewünschten Tools zu verwenden, generieren Sie ein Servicekonto-Token und kopieren Sie es für die Verwendung in der Konfigurationsdatei in die Zwischenablage. Befolgen Sie die Grafana-Servicekonto-Dokumentation für Details zum Erstellen von Servicekonto-Tokens. Tipp: Wenn Sie sich nicht wohl dabei fühlen, feingranulare RBAC-Bereiche zu konfigurieren, ist eine einfachere (aber weniger restriktive) Option, dem Servicekonto die integrierte Rolle Editor zuzuweisen. Dies gewährt breiten Lese-/Schreibzugriff, der die meisten MCP-Servervorgänge abdeckt – verwenden Sie es, wenn Bequemlichkeit strengere Anforderungen an minimale Rechte überwiegt.

Hinweis: Die Umgebungsvariable GRAFANA_API_KEY ist veraltet und wird in einer zukünftigen Version entfernt. Bitte migrieren Sie zur Verwendung von GRAFANA_SERVICE_ACCOUNT_TOKEN. Der alte Variablenname funktioniert weiterhin für die Abwärtskompatibilität, zeigt jedoch Veraltungswarnungen.

Lesen des Servicekonto-Tokens aus einer Datei

Anstatt das Token inline über GRAFANA_SERVICE_ACCOUNT_TOKEN zu übergeben, können Sie GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE auf einen Dateipfad verweisen, der das Token enthält. Die Datei wird bei jeder Anfrage frisch gelesen, sodass rotierte Token automatisch übernommen werden, ohne den Server neu zu starten. Dies ist besonders nützlich in Kubernetes, wo ein als Volume gemountetes Secret direkt aktualisiert wird, wenn sich das zugrunde liegende Secret ändert (typischerweise innerhalb von ~1 Minute). In Kombination mit dem Pro-Anfrage-Client-Cache – der auf dem Token-Wert basiert – erzeugt ein rotiertes Token transparent einen neuen Client ohne Pod-Neustart und ohne Ausfallzeit:

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

Umgebender Leerraum (einschließlich eines abschließenden Zeilenumbruchs) wird 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 angeben, mit welcher Organisation Sie interagieren möchten, entweder über:

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 (Header hat Vorrang vor der Umgebungsvariable – das heißt, Sie können auch eine Standard-Organisation festlegen).

Wenn eine Organisations-ID angegeben ist, setzt der MCP-Server den X-Grafana-Org-Id-Header auf alle Anfragen an Grafana, um sicherzustellen, dass Operationen im Kontext der angegebenen Organisation ausgeführt werden.

Dynamische (pro Aufruf) Organisationsauswahl

Die obigen Optionen legen die Organisation für die gesamte Verbindung fest. Um einer einzelnen Verbindung zu ermöglichen, pro Tool-Aufruf verschiedene Organisationen anzusprechen, starten Sie den Server mit dem --dynamic-multi-org-Flag. Dies ist standardmäßig deaktiviert.

Wenn aktiviert, akzeptiert jedes Tool ein optionales orgId-Argument, das die Organisation der Verbindung für diesen Aufruf überschreibt (wobei sowohl der X-Grafana-Org-Id-Header als auch für App-Plattform-APIs der aufgelöste Kubernetes-Namespace gesteuert werden). Proxierte Datasource-Tools werden zusätzlich über jede Organisation hinweg erkannt, auf die die Anmeldeinformationen zugreifen können. Aufrufe, die orgId weglassen, verwenden die Standard-Organisation der Verbindung.

Dies funktioniert nur für Anmeldeinformationen, die zu mehr als einer Organisation gehören (z. B. eine Benutzer- oder On-Behalf-of-Identität); ein Service-Account-Token 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

Sie können beliebige HTTP-Header zu allen Grafana-API-Anfragen hinzufügen, indem Sie die Umgebungsvariable GRAFANA_EXTRA_HEADERS verwenden. Der Wert sollte ein JSON-Objekt sein, das Header-Namen auf Werte abbildet.

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

Sie können alle Anfragen, die dieser Server an Grafana stellt, über einen SOCKS5-Proxy leiten, indem Sie die Umgebungsvariable GRAFANA_SOCKS5_PROXY verwenden. Der Proxy ist auf den Grafana-Datenverkehr dieses Servers beschränkt: Er ändert nicht die globalen Variablen HTTP_PROXY/HTTPS_PROXY, und wenn gesetzt, überschreibt er deren Proxy-Auswahl nur für Grafana-Transporte, ohne andere MCP-Server oder Ihre Shell-Sitzung zu beeinflussen. Wenn nicht gesetzt, bleibt das Verhalten unverändert.

Die URL muss das Schema socks5:// oder socks5h:// verwenden (Go behandelt sie identisch: Die Hostnamenauflösung wird an den Proxy delegiert) und kann Anmeldeinformationen 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 ist ein Startfehler, und wenn das Erstellen einer proxied Verbindung zur Laufzeit fehlschlägt, schlägt der Server geschlossen fehl, anstatt Grafana-Datenverkehr stillschweigend direkt zu senden.

Weiterleitung von Headern vom Client (nur Streamable-HTTP)

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

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

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 allen in GRAFANA_EXTRA_HEADERS definierten Headern zusammengeführt. Wenn ein Header-Name in beiden vorkommt, hat der Wert aus der eingehenden Anfrage für diese Anfrage Vorrang.

Trace-Kontext-Header (traceparent, tracestate, baggage) sind die Ausnahme: Der Server propagiert den Trace-Kontext selbst, sodass ein weitergeleiteter Wert niemals den von ihm injizierten überschreibt. Siehe Observability.

Sie haben mehrere Optionen, um mcp-grafana zu installieren:
- uvx (empfohlen): Wenn Sie uv installiert haben, ist keine zusätzliche Einrichtung erforderlich – uvx wird automatisch heruntergeladen und den Server ausführen:
```
uvx mcp-grafana
```
- Docker-Image: Verwenden Sie das vorgefertigte Docker-Image von Docker Hub.
  
  Wichtig: Der Entrypoint des Docker-Images ist so konfiguriert, dass der MCP-Server standardmäßig im SSE-Modus ausgeführt wird, aber die meisten Benutzer möchten 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 den Standardwert explizit mit -t stdio überschreiben und das -i-Flag einschließen, um stdin offen zu halten:
```
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: In den SSE- und streamable-http-Modi bindet der Container eine Nicht-Loopback-Adresse (0.0.0.0:8000). Ohne einen Caller-Token startet der Server , protokolliert jedoch einen Sicherheitsfehler (auf der error-Protokollebene, sodass er nicht durch --log-level verborgen wird; und er wird sich weigern, in einer zukünftigen Hauptversion zu starten). Setzen Sie MCP_GRAFANA_SERVER_TOKEN, um einen Authorization: Bearer <token> von Clients zu verlangen (empfohlen). Der STDIO-Modus ist nicht betroffen. Siehe Caller-Authentifizierung.
  1. SSE-Modus: In diesem Modus läuft der Server als HTTP-Server, mit dem Clients eine Verbindung herstellen. Sie müssen Port 8000 mit dem -p-Flag 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 arbeitet der Server als unabhängiger Prozess, der mehrere Client-Verbindungen verarbeiten kann. Sie müssen Port 8000 mit dem -p-Flag freigeben: Für diesen Modus müssen Sie den Standardwert explizit 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 HTTPS-streamable-HTTP-Modus mit 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 platzieren Sie sie in Ihrem $PATH.
- Aus dem Quellcode erstellen: Wenn Sie eine Go-Toolchain installiert haben, können Sie sie auch aus dem Quellcode erstellen und installieren, indem Sie die Umgebungsvariable GOBIN verwenden, um das Verzeichnis anzugeben, in dem die Binärdatei installiert werden soll. Dies sollte auch in Ihrem $PATH sein.
```
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
```

Fügen Sie die Serverkonfiguration zu Ihrer Client-Konfigurationsdatei hinzu. Zum Beispiel für Claude Desktop:

Wenn Sie uvx verwenden:

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

Wenn Sie die Binärdatei verwenden:

{
  "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 Error: spawn mcp-grafana ENOENT in Claude Desktop sehen, müssen Sie den vollständigen Pfad zu mcp-grafana angeben.

Wenn Sie Docker verwenden:

{
  "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 -t stdio-Argument ist hier wesentlich, da es den Standard-SSE-Modus im Docker-Image überschreibt.

Verwenden von VSCode mit Remote-MCP-Server

Wenn Sie VSCode verwenden und den MCP-Server im SSE-Modus ausführen (was der Standard ist, wenn Sie das Docker-Image ohne Überschreiben des Transports verwenden), stellen Sie sicher, dass Ihre .vscode/settings.json Folgendes enthält:

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

Für den HTTPS-streamable-HTTP-Modus mit 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 das -debug-Flag zum Befehl hinzufügen. Dies bietet eine detaillierte Protokollierung von HTTP-Anfragen und -Antworten zwischen dem MCP-Server und der Grafana-API, was bei der Fehlerbehebung hilfreich sein kann.

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

Wenn Sie die Binärdatei verwenden:

{
  "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>"
      }
    }
  }
}

Wenn Sie Docker verwenden:

{
  "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 -t stdio-Argument erforderlich, um den Standard-SSE-Modus im Docker-Image zu überschreiben.

TLS-Konfiguration

Wenn Ihre Grafana-Instanz hinter mTLS liegt 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 TLS-Private-Key-Datei für die Client-Authentifizierung
--tls-ca-file: Pfad zur TLS-CA-Zertifikatsdatei für die Serververifizierung
--tls-skip-verify: TLS-Zertifikatsverifizierung überspringen (unsicher, nur für Tests 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 HTTP-Clients angewendet, die vom MCP-Server verwendet werden, einschließlich:

Der Haupt-Grafana-OpenAPI-Client
Prometheus-Datasource-Clients
Loki-Datasource-Clients
Incident-Management-Clients
Alerting-Clients
Asserts-Clients

Direkte CLI-Verwendungsbeispiele:

Für Tests 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

Mit nur benutzerdefiniertem CA-Zertifikat:

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

Programmatische Verwendung:

Wenn Sie diese Bibliothek programmatisch 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 programmatische Konstruktion), validieren Sie URLs vorab, um einen erreichbaren Panikzustand 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 Streamable-HTTP-Transport)

Wenn Sie den streamable-HTTP-Transport (-t streamable-http) verwenden, können Sie den MCP-Server so konfigurieren, dass er HTTPS anstelle von 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 Server-HTTPS (für TLS erforderlich)
--server.tls-key-file: Pfad zur TLS-Private-Key-Datei für Server-HTTPS (für TLS erforderlich)

Hinweis: Diese Flags sind völlig getrennt von den oben dokumentierten Client-TLS-Flags. Die Client-TLS-Flags konfigurieren, wie der MCP-Server eine Verbindung zu Grafana herstellt, während diese Server-TLS-Flags konfigurieren, wie Clients eine Verbindung zum MCP-Server herstellen, wenn sie den streamable-HTTP-Transport verwenden.

Beispiel mit HTTPS-streamable-HTTP-Server:

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

Dies würde den MCP-Server auf HTTPS-Port 8443 starten. Clients würden dann eine Verbindung zu https://localhost:8443/ anstelle von 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- (-t streamable-http) Transporte stellt der MCP-Server einen Health-Check-Endpunkt unter /healthz bereit. Dieser Endpunkt kann von Load-Balancern, Überwachungssystemen oder Orchestrierungsplattformen verwendet werden, um zu überprüfen, ob der Server läuft und Verbindungen akzeptiert.

Endpunkt: GET /healthz

Antwort:

Statuscode: 200 OK
Body: 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 verfügbar, wenn SSE- oder streamable-HTTP-Transporte verwendet werden. Er ist nicht verfügbar, wenn der stdio-Transport (-t stdio) verwendet wird, da stdio keinen HTTP-Server bereitstellt.

Anonyme Nutzungsstatistiken

Der Server kann anonyme Nutzungsstatistiken über sich selbst an Grafana Labs melden: welche Tools aufgerufen wurden, wie viele dieser Aufrufe fehlgeschlagen sind und wie der Server konfiguriert ist. Ein Bericht deckt einen Server-Prozess ab – nicht einen Benutzer und nicht eine Konversation – und wird alle 4 Stunden plus einmal beim Herunterfahren gesendet. Die Berichterstattung ist standardmäßig aktiviert. Um dies zu deaktivieren, setzen Sie --usage-stats=disabled, GRAFANA_USAGE_STATS=disabled oder DO_NOT_TRACK=1. Tool-Argumente, Ressourcennamen, Abfragen, Logzeilen, Fehlermeldungen und Anmeldedaten werden niemals gesendet. Flags werden nur nach Namen erfasst, niemals nach Wert, und die Grafana-Instanz wird nur als cloud oder self_hosted beschrieben – niemals nach URL, Hostname, Stack-Slug oder Organisation. Nichts ist pro Benutzer, pro Sitzung oder pro 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 ebenfalls die Berichterstattung, gemäß der toolübergreifenden DO_NOT_TRACK-Konvention. Nur 1 hat eine Wirkung, es kann nur deaktivieren, und sowohl --usage-stats als auch GRAFANA_USAGE_STATS überschreiben es, sodass ein Host, der es global setzt, einen Server dennoch wieder aktivieren kann.

GRAFANA_USAGE_STATS_ENDPOINT ändert das Ziel. Es ist kein Opt-out.

Für die vollständige Feldliste, was niemals gesendet wird, wie die Daten zu lesen sind und ihre Einschränkungen, siehe Anonyme Nutzungsstatistiken.

Beobachtbarkeit

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

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

Metriken

Bei Verwendung der SSE- oder streamable-HTTP-Transporter aktivieren Sie Prometheus-Metriken mit dem --metrics-Flag:

# 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:

Metrik	Typ	Beschreibung
`mcp_server_operation_duration_seconds`	Histogramm	Dauer von MCP-Operationen (Labels: `mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`)
`http_server_request_duration_seconds`	Histogramm	Dauer von HTTP-Serveranfragen (von otelhttp)

Hinweis: Metriken sind nur bei Verwendung der SSE- oder streamable-HTTP-Transporter verfügbar. Sie sind beim stdio-Transport nicht verfügbar.

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

Metrik	Typ	Beschreibung
`mcp_loki_guardrail_admitted_total`	Zähler	Abfragen, die alle aktivierten Prüfungen bestanden haben (Labels: `backend`)
`mcp_loki_guardrail_would_block_total`	Zähler	Abfragen, die eine Prüfung im `shadow`-Modus nicht bestanden haben und trotzdem ausgeführt wurden (Labels: `backend`, `reason`)
`mcp_loki_guardrail_blocked_total`	Zähler	Abfragen, die im `enforce`-Modus abgelehnt wurden (Labels: `backend`, `reason`)
`mcp_loki_guardrail_fail_open_total`	Zähler	Abfragen, die die Schutzmaßnahme nicht auswerten konnte und zugelassen hat (Labels: `backend`, `cause`)

reason ist eines von selector, range, bytes; cause ist eines von unparseable, estimate_failed; backend ist eines von 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 geschützte Population partitionieren. Siehe Beobachtbarkeit für Hinweise zum Lesen während eines shadow → enforce-Rollouts.

Bibliotheks-Einbettungen sollten GrafanaConfig.MeterProvider setzen (das Metrik-Pendant zu GrafanaConfig.Logger): Die Schutzmaßnahme läuft innerhalb eines Tool-Handlers, hat also keine Konstruktoroption, und ein Prozess, der ein Noop-globales MeterProvider installiert, würde sonst jede Aufzeichnung verwerfen.

Protokollierung langsamer Anfragen

Das --slow-request-threshold-Flag gibt ein strukturiertes Log-Ereignis aus, wenn eine MCP-Anfrage (Tool-Aufruf, Liste, Ressourcenlesen usw.) die angegebene Dauer überschreitet. Es ist nützlich zur Diagnose langsamer Abfragen und Tool-Aufrufe, ohne im vollständigen Debug-Log zu ertrinken.

# 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 Log-Ereignis trägt diese strukturierten Attribute:

Attribut	Beschreibung
`mcp.method`	Die MCP-Methode (z. B. `tools/call`, `tools/list`, `resources/read`)
`duration`	Beobachtete Anfragedauer
`threshold`	Konfigurierter Schwellenwert
`tool`	Tool-Name (nur bei `tools/call`-Methoden vorhanden)
`error`	Fehlerwert, wenn die Anfrage fehlgeschlagen ist (Best-Effort-Kontext; Inhalt wird durch das Upstream-Fehler-Wrapping gesteuert)
`error.type`	Fehlerklassifizierung mit begrenzter Kardinalität (`_OTHER` für untypisierte Fehler)

Die Protokollierung langsamer Anfragen funktioniert auf allen Transportern (einschließlich stdio) und erfordert kein --metrics. Der Standard-Schwellenwert von 0 deaktiviert sie vollständig. Proxierte Tools fließen durch tools/call und werden automatisch abgedeckt.

Tracing

Verteiltes Tracing wird über standardmäßige OTEL_*-Umgebungsvariablen konfiguriert und funktioniert unabhängig vom --metrics-Flag. 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-Namensgebung (tools/call <tool_name>) und enthalten Attribute wie gen_ai.tool.name, mcp.method.name und mcp.session.id. Der Server unterstützt auch die W3C-Trace-Kontextweitergabe aus dem _meta-Feld von Tool-Aufrufanfragen.

Logs

Wenn OTEL_EXPORTER_OTLP_ENDPOINT (oder das signalspezifische OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) gesetzt ist, exportiert der Server zusätzlich zum vorhandenen Klartext-Stderr-Ausgang strukturierte Logs über OTLP/gRPC. Die otelslog-Brücke hängt automatisch trace_id und span_id aus der aktiven Span an, sodass Log-Datensätze mit den Traces korrelieren, die der Server bereits ausgibt.

Traces und Logs lösen ihre Endpunkte unabhängig auf, sodass die beiden Signale separat aktiviert werden können: Nur OTEL_EXPORTER_OTLP_TRACES_ENDPOINT zu setzen aktiviert Tracing ohne Log-Export, nur OTEL_EXPORTER_OTLP_LOGS_ENDPOINT zu setzen aktiviert Log-Export ohne Tracing, und das generische OTEL_EXPORTER_OTLP_ENDPOINT aktiviert beides.

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

OTEL_LOGS_EXPORTER=none

Dies verhindert, dass der Server unabhängig von der Endpunktkonfiguration einen OTLP-Logs-Exporter erstellt, und vermeidet Fehler wie unknown service opentelemetry.proto.collector.logs.v1.LogsService.

Die Stderr-Protokollierung bleibt unverändert, wenn die OTLP-Protokollierung aktiviert ist; Sie können sich weiterhin auf Container-Logs verlassen oder Stderr bei Bedarf 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

Der Transport ist OTLP/gRPC (Standardport 4317). Logs können direkt an jedes verwaltete Backend gesendet werden, das OTLP/gRPC akzeptiert – z. B. Grafana Cloud – indem Sie OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (oder das generische OTEL_EXPORTER_OTLP_ENDPOINT) auf den entfernten gRPC-Endpunkt richten und die Authentifizierung über OTEL_EXPORTER_OTLP_LOGS_HEADERS (oder OTEL_EXPORTER_OTLP_HEADERS) bereitstellen, analog zum Tracing-Beispiel oben. Ein lokaler OTel-Collector ist optional – nützlich für Fan-out, Batching oder Multi-Backend-Routing, 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 überschreiben ihre generischen OTEL_EXPORTER_OTLP_*-Gegenstücke – siehe die OTel-Exporter-Spezifikation für die vollständige Liste und Vorrangregeln.

Wenn der konfigurierte Collector nicht erreichbar ist, werden Log-Datensätze im Speicher gepuffert (Standardwarteschlange: 2048) und die ältesten Datensätze werden verworfen, sobald die Warteschlange voll ist. Der Prozess läuft weiter, ohne den Dienst zu blockieren. Konfigurieren Sie einen lokalen OTel-Collector, wenn Sie verlustfreies Puffern während Ausfällen benötigen.

Logs werden auch unter dem stdio-Transport exportiert, was die Zentralisierung von Logs lokaler mcp-grafana-Instanzen erleichtert, die von IDE-Clients aufgerufen werden.

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

Loki-Abfrage-Durchsetzung

--loki-enforced-matchers ermöglicht einem Operator, einzuschränken, welche Loki-Log-Streams der Server jemals lesen kann, indem eine feste Menge von LogQL-Label-Matchern per UND in jede native Loki-Abfrage eingefügt wird, die der Server ausgibt. Dies ist nützlich, wenn eine Datenquelle Streams enthält, die nicht offengelegt werden dürfen (z. B. Logs, die sensible Informationen enthalten können), Sie aber den Zugriff nicht auf der Grafana- oder Loki-Ebene einschränken können (OSS hat keine Zugriffskontrolle pro Datenquelle oder pro Benutzer auf Label-Ebene).

# 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

So funktioniert es:

Die Matcher werden beim Start einmal geparst (ungültige Eingabe bricht den Server ab) und an jeden Stream-Selektor in jeder Abfrage angehängt. Da Loki Matcher innerhalb eines Selektors per UND verknüpft, kann eine Benutzerabfrage Ergebnisse nur eingrenzen innerhalb der erzwungenen Grenzen – sie kann sie niemals erweitern. Ein Benutzerselektor, der mit der Richtlinie in Konflikt steht (z. B. die Anforderung von {namespace="vault"} unter einem Ausschluss), gibt einfach nichts zurück.
Es deckt query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names und list_loki_label_values ab.
Es schlägt geschlossen fehl: Jede Abfrage, die nicht geparst werden kann, wird abgelehnt, statt ungefiltert gesendet zu werden.
VictoriaLogs-Datenquellen verwenden LogsQL, das nicht sicher umgeschrieben werden kann, daher werden sie vollständig verweigert, während die Durchsetzung aktiviert ist.
Rein negative Matcher können die Label-Enumeration-Endpunkte nicht eingrenzen (Loki lehnt einen eigenständigen Selektor ohne positiven Matcher ab). Steuern Sie diesen Randfall mit --loki-label-enumeration-fallback (reject standardmäßig oder unfiltered, um die uneingeschränkte Enumeration von Label-Metadaten zu erlauben – Logzeilen werden niemals offengelegt). Positive/Allowlist-Matcher sind nicht betroffen.

[!IMPORTANT] Die Durchsetzung gilt nur für die Loki-Abfrage-Tools. Andere Tools können Loki-Log-Daten über Pfade erreichen, die das durchgesetzte Backend nie berühren. Damit die Einschränkung tatsächlich gilt, müssen Sie diese ebenfalls deaktivieren:

--disable-api – grafana_api_request kann den Loki-Datenquellen-Proxy direkt abfragen (vollständiger Bypass).

--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 Loki serverseitig über alle Streams liest. Nur registriert, wenn Schreib-Tools aktiviert sind, also schließt --disable-write es ebenfalls.

Der Server protokolliert beim Start eine Warnung, die jedes dieser noch aktivierten Tools nennt. run_panel_query ist sicher (es verwendet den durchgesetzten Abfragepfad erneut). Tempo-Tools fragen Traces ab, nicht Loki-Logs, sind also kein Bypass. Dashboard- Schnappschüsse (--disable-snapshot) können ebenfalls Log-Panel-Daten einbetten, die außerhalb der Durchsetzung erfasst wurden.

Fehlerbehebung

Grafana-Versionskompatibilität

Wenn Sie den folgenden Fehler bei der Verwendung von Datenquellen-bezogenen Tools erhalten:

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

Dies deutet typischerweise darauf hin, dass Sie eine Grafana-Version vor 9.0 verwenden. Der /datasources/uid/{uid}-API-Endpunkt wurde in Grafana 9.0 eingeführt, und Datenquellenoperationen schlagen bei 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! Bitte lesen Sie zuerst CONTRIBUTING.md – es behandelt, was in diesen Server gehört und wie Sie es vorschlagen.

Wenn Sie ein neues Tool hinzufügen, öffnen Sie bitte einen Tool-Vorschlag, bevor Sie den Code schreiben. Jedes standardmäßig aktivierte Tool wird bei jeder Anfrage von jedem Benutzer an das Modell gesendet. Wir besprechen die Idee daher lieber, als einen fertigen Pull-Request abzulehnen. Fehlerbehebungen, Dokumentation, Tests und neue Parameter für bestehende Tools benötigen keinen Vorschlag – senden Sie einfach einen PR.

Dieses Projekt ist in Go geschrieben. Installieren Sie Go gemäß den Anweisungen für Ihre Plattform.

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

make 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. Genau wie das veröffentlichte Docker-Image verwendet auch dieses benutzerdefinierte Image standardmäßig den SSE-Modus als Entrypoint. Um das Image zu erstellen, verwenden Sie:

make build-image

Und um das Image im SSE-Modus (dem Standard) auszuführen, verwenden Sie:

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

Wenn Sie es stattdessen im STDIO-Modus ausführen müssen, überschreiben Sie die Transporteinstellung:

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

Testen

Es gibt drei Arten von Tests:

Unit-Tests (keine externen Abhängigkeiten erforderlich):

make test-unit

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

make test

Integrationstests (erfordert laufende Docker-Container):

make test-integration

Cloud-Tests (erfordert eine Cloud-Grafana-Instanz und Anmeldedaten):

make test-cloud

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

Umfassendere Integrationstests erfordern eine lokal auf Port 3000 laufende Grafana-Instanz; Sie können eine mit Docker Compose starten:

docker-compose up -d

Die Integrationstests können mit folgendem Befehl ausgeführt werden:

make test-all

Wenn Sie weitere Tools hinzufügen, fügen Sie bitte Integrationstests für diese hinzu. Die vorhandenen Tests sollten ein guter Ausgangspunkt sein.

Linting

Um den Code zu linten, führen Sie Folgendes aus:

make lint

Dies beinhaltet einen benutzerdefinierten Linter, der auf nicht maskierte Kommas in jsonschema-Struct-Tags prüft. Die Kommas in description-Feldern müssen mit \\, maskiert werden, um eine stille Kürzung zu verhindern. Sie können nur diesen Linter mit folgendem Befehl ausführen:

make lint-jsonschema

Weitere Details finden Sie in der JSONSchema-Linter-Dokumentation.

Lizenz

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