Grafana

offiziell

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

GitHub
3.4k
Dieses MCP ausprobierenGesponsert

Was kann man mit Grafana MCP machen?

  • Dashboards suchen und inspizieren — Verwenden Sie search_dashboards und get_dashboard_summary, um Dashboards zu finden und kompakte Übersichten ohne vollständiges JSON zu erhalten.
  • Prometheus und Loki abfragen — Führen Sie PromQL- und LogQL-Abfragen gegen Ihre Datenquellen aus, einschließlich Metadaten und Histogramm-Perzentilen.
  • Alerting verwalten — Listen Sie Alert-Regeln auf, erstellen, aktualisieren und löschen Sie sie, und zeigen Sie Benachrichtigungsrichtlinien und Kontaktpunkte an.
  • Deeplinks generieren — Erstellen Sie präzise URLs zu Dashboards, Panels und Explore mit Zeitbereichen über die Navigationswerkzeuge.
  • Panel-Abfragen ausführen — Führen Sie die Abfrage eines Dashboard-Panels mit benutzerdefinierten Zeitbereichen und Variablen mithilfe von run_panel_query aus.

Dokumentation

Grafana MCP Server

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

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

Ersetzen Sie für Grafana Cloud GRAFANA_URL durch Ihre Instanz-URL (z. B. https://myinstance.grafana.net). Weitere Installationsoptionen einschließlich 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 mit früheren Versionen aufgrund fehlender API-Endpunkte nicht korrekt.

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 oder anderen Metadaten finden
  • Dashboard nach UID abrufen: Vollständige Dashboard-Details anhand der eindeutigen Kennung abrufen. Warnung: Große Dashboards können erheblichen Kontextfensterplatz beanspruchen.
  • Dashboard-Zusammenfassung abrufen: Eine kompakte Übersicht über ein Dashboard 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: Vorhandene Dashboards ändern oder neue erstellen. Warnung: Erfordert vollständiges Dashboard-JSON, das große Mengen an Kontextfensterplatz beanspruchen 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 zum Ausführen von Panel-Abfragen 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 umfassen nun mehrere Strategien zur effektiven Verwaltung der Kontextfensternutzung (Issue #101):

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

Datenquellen

  • Datenquelleninformationen auflisten und abrufen: Alle konfigurierten Datenquellen anzeigen und detaillierte Informationen zu jeder einzelnen 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 (unterstützt sowohl Sofort- als auch Bereichsmetrikabfragen) gegen Prometheus-Datenquellen ausführen.
  • Prometheus-Metadaten abfragen: Metrikmetadaten, Metriknamen, Labelnamen und Labelwerte von Prometheus-Datenquellen abrufen.
  • Histogramm-Perzentile abfragen: Histogramm-Perzentilwerte (p50, p90, p95, p99) mit 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 mit entweder InfluxQL (v1.x) oder Flux (v2.x) ausführen. Der Dialekt wird aus der Datenquellenkonfiguration abgeleitet oder kann explizit über den Parameter dialect festgelegt werden.

ClickHouse-Abfragen

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

  • ClickHouse-Tabellen auflisten: Alle Tabellen in einer ClickHouse-Datenbank mit Zeilenanzahl und Größen auflisten.
  • Tabellenschema beschreiben: Spaltennamen, Typen und Metadaten für eine ClickHouse-Tabelle abrufen.
  • ClickHouse abfragen: SQL-Abfragen mit Unterstützung für Grafana-Makros und Variablensubstitution 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 ermitteln.
  • 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 Unterstützung für Zeitbereiche ausführen.

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 ermitteln.
  • Graphite-Tags auflisten: Verfügbare Graphite-Tags und Tag-Werte auflisten.
  • Graphite-Dichte abfragen: Graphite-Metrikdichte für ein bestimmtes Muster abfragen.

Athena-Abfragen

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

  • Athena-Kataloge auflisten: Verfügbare Datenkataloge ermitteln (z. B. AwsDataCatalog, Iceberg-Connectors).
  • Athena-Datenbanken auflisten: Datenbanken in einem Athena-Katalog auflisten.
  • Athena-Tabellen auflisten: Tabellen in einer Athena-Datenbank auflisten.
  • Athena-Tabelle beschreiben: Spaltennamen für eine Athena-Tabelle abrufen.
  • Athena abfragen: SQL-Abfragen gegen Amazon Athena über Grafana mit Makrosubstitution, Limit-Durchsetzung und Unterstützung für Vorlagenvariablen ausführen.

Snowflake-Abfragen

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

Abfragen laufen über Grafanas Snowflake-Datenquelle (Grafana-Enterprise-Plugin grafana-snowflake-datasource), sodass die Authentifizierung durch die Datenquellenkonfiguration in Grafana erfolgt – Anmeldeinformationen werden vom MCP-Server nie gesehen. Dies ist dasselbe Modell wie bei den ClickHouse-Tools.

  • Snowflake-Tabellen auflisten: Tabellen (mit Datenbank, Schema, Art, Zeilenanzahl und Größe) über INFORMATION_SCHEMA.TABLES ermitteln. Optionale Datenbank-/Schemafilter.
  • Tabellenschema beschreiben: Spaltennamen, Datentypen, Nullbarkeit, Standardwerte und Kommentare für eine Snowflake-Tabelle abrufen.
  • Snowflake abfragen: SQL-Abfragen mit Unterstützung für Makro- und Variablensubstitution ausführen. Nützlich zum Abfragen von Snowflake-Ereignistabellen (z. B. SNOWFLAKE.TELEMETRY.EVENTS) für Protokolle und Traces oder beliebiger Benutzertabellen.
    • Unterstützte Makros: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (Unix-ms), $__interval (Sekunden), $__interval_ms und ${varname} für die Substitution von Vorlagenvariablen.

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 mit entweder Lucene-Abfragesyntax oder Elasticsearch-Query-DSL ausführen. Unterstützt das Filtern nach Zeitbereich und das Abrufen von Protokollen, Metriken oder beliebigen indizierten Daten. Gibt Dokumente mit ihrem Index, ihrer ID, Quellfeldern und optionalem Relevanzscore 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 partieller Elasticsearch-kompatibler Query-DSL ausführen. Unterstützt das Filtern nach Zeitbereich und das Abrufen von Protokollen oder anderen indizierten Dokumenten. Gibt Dokumente mit ihrem Index, ihrer ID, Quellfeldern und optionalem Relevanzscore zurück.

Agent-Beobachtbarkeit

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

  • Konversationen auflisten und durchsuchen: Aktuelle LLM-Konversationen auflisten oder mit einem Filterausdruck (Modell, Anbieter, Agent, Status, Fehlertyp, Eval-Ergebnisse und mehr) über einen Zeitbereich durchsuchen. Suchergebnisse enthalten Fehlerzahlen, Bewertungszusammenfassungen, Evaluierungszusammenfassungen und Trace-IDs.
  • Konversationsdetails abrufen: Eine einzelne Konversation mit allen ihren Generationen einschließlich Prompts und Ausgaben abrufen.
  • Generierungsdetails und Bewertungen abrufen: Eine einzelne Generation anhand der ID abrufen sowie ihre Evaluierungsbewertungen (Evaluator, Bewertungsschlüssel, Wert, bestanden, Erklärung).
  • Agent-Katalog lesen: Die Agenten auflisten, die Telemetrie senden, eine Agentenversion vollständig abrufen (vollständiger System-Prompt, jedes Tool mit seinem JSON-Schema und die Modelle, auf denen es lief), den Versionsverlauf eines Agenten durchgehen und aggregierte Evaluierungsbewertungen pro Version vergleichen. Effektive Versionen sind sha256:-Hashes, die eine Tool-Änderung nie beeinflusst; für einen Agenten, der keine eigene Version meldet, werden sie aus dem System-Prompt gehasht, sodass eine Prompt-Bearbeitung eine neue Version erzeugt. Katalog- und Versionszeilen tragen eine token_estimate, die es wert ist, vor dem Abrufen eines vollständigen Prompts überprüft zu werden.
  • Evaluatoren und Vorlagen prüfen: Die Evaluatoren lesen, von denen eine Bewertung stammt, die Vorlagen, aus denen sie abgeleitet wurden, sowie die Judge-Anbieter und Modelle, die für LLM-Judge-Evaluatoren verfügbar sind. Mit aktivierten Schreibwerkzeugen auch Evaluatoren erstellen, forken, testen und löschen.
  • Eval-Regeln und Guards prüfen: Die asynchronen Eval-Regeln lesen, die Evaluatoren an Produktionsdatenverkehr binden, sowie die Guards (Hook-Regeln), die inline ausgeführt werden und warnen oder ablehnen können. Mit aktivierten Schreibwerkzeugen auch erstellen, aktualisieren, in der Vorschau anzeigen und löschen. Schreibvorgänge sowie die nicht persistierenden Operationen preview_rule und test_evaluator benötigen die Berechtigung grafana-agento11y-app.eval:write, die durch die Rolle Agento11y-Administrator gewährt wird.
  • Gespeicherte Konversationen und Sammlungen kuratieren: Die gespeicherten Konversationen lesen (Lesezeichen, die einer Konversation eine stabile ID, einen Namen und Tags geben) sowie die Sammlungen, die sie gruppieren, einschließlich der Mitgliederanzahl jeder Sammlung und der Sammlungen, die in jeder Zeile gespeicherter Konversationen eingebettet sind. Mit aktivierten Schreibwerkzeugen auch eine Konversation mit Lesezeichen versehen, Sammlungen erstellen und bearbeiten sowie Mitglieder hinzufügen oder entfernen. Diese Schreibvorgänge benötigen dieselbe Berechtigung grafana-agento11y-app.eval:write.
  • Testsuiten lesen und bearbeiten: Die versionierten Testsuiten auflisten, gegen die Offline-Experimente ausgeführt werden, eine mit ihrem vollständigen Versionsverlauf lesen und durch die Testfälle einer Version blättern. Mit aktivierten Schreibwerkzeugen auch eine Suite erstellen, sie umbenennen oder neu taggen, eine Entwurfsversion öffnen, veröffentlichen sowie 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: Die Evaluierungsläufe über eine Testsuit auflisten und einen mit seiner Haupt-Bestehensquote, Kosten und Token-Summen lesen. Über einen Bericht pro Testfall zu Versuchen, ihren Bewertungen mit der Erklärung jedes Judges und ihren Artefakt-Metadaten durchdringen. Mit aktivierten Schreibwerkzeugen 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 Assistent

Hinweis: Assistent-Tools sind standardmäßig deaktiviert und erfordern die Installation des Grafana Assistant-Plugins (grafana-assistant-app) auf der Ziel-Grafana-Instanz. Sie sind außerdem Schreibtools (der Assistent kann den Stack-Zustand ändern), daher werden sie übersprungen, wenn --disable-write gesetzt ist. Um sie zu aktivieren, fügen Sie assistant zu Ihrem --enabled-tools-Flag hinzu.

  • Assistent fragen: Senden Sie eine Aufforderung in natürlicher Sprache an Grafana Assistant und warten Sie auf die vollständige Textantwort. Der Assistent kann Tools, Metriken, Logs und anderen Stack-Kontext verwenden – umfassender als das Auslösen einer einzelnen isolierten Datenquellen-Abfrage. Geben Sie den zurückgegebenen contextId in einem Folgeaufruf zurück, um dieselbe Konversation fortzusetzen. Komplexe Aufgaben können mehrere Minuten dauern; der Aufruf blockiert, bis die Antwort abgeschlossen 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 und Hinzufügen von Aktivitäten zu Vorfällen.

Sift-Untersuchungen

  • Sift-Untersuchungen auflisten: Rufen Sie eine Liste von Sift-Untersuchungen ab, mit Unterstützung für einen Limit-Parameter.
  • Sift-Untersuchung abrufen: Rufen Sie Details einer bestimmten Sift-Untersuchung anhand ihrer UUID ab.
  • Sift-Analysen abrufen: Rufen Sie eine bestimmte Analyse aus einer Sift-Untersuchung ab.
  • Fehlermuster in Logs finden: Erkennen Sie erhöhte Fehlermuster in Loki-Logs mithilfe von Sift.
  • Langsame Anfragen finden: Erkennen Sie langsame Anfragen mithilfe von Sift (Tempo).

Alarmierung

  • Alarmregelinformationen auflisten und abrufen: Zeigen Sie Alarmregeln und deren Status (auslösend/normal/Fehler usw.) in Grafana an. Unterstützt sowohl Grafana-verwaltete Regeln als auch datenquellenverwaltete Regeln von 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

  • Dienstepläne auflisten und verwalten: Zeigen Sie Rufbereitschaftspläne in Grafana OnCall an und verwalten Sie diese.
  • Schichtdetails abrufen: Rufen Sie detaillierte Informationen zu bestimmten Rufbereitschaftsschichten ab.
  • Aktuelle Rufbereitschaftsbenutzer abrufen: Sehen Sie, welche Benutzer derzeit für einen Zeitplan Rufbereitschaft haben.
  • Teams und Benutzer auflisten: Zeigen Sie alle OnCall-Teams und -Benutzer an.
  • Alarmgruppen auflisten: Zeigen Sie Alarmgruppen von Grafana OnCall an und filtern Sie sie nach verschiedenen Kriterien wie Status, Integration, Labels und Zeitbereich.
  • Alarmgruppendetails abrufen: Rufen Sie detaillierte Informationen zu einer bestimmten Alarmgruppe anhand ihrer ID ab.

Admin

Hinweis: Admin-Tools sind standardmäßig deaktiviert. Fügen Sie admin zu Ihrem --enabled-tools-Flag hinzu, um sie zu aktivieren.

  • Teams auflisten: Zeigen Sie alle konfigurierten Teams in Grafana an.
  • Benutzer auflisten: Zeigen Sie alle Benutzer einer Organisation in Grafana an.
  • Alle Rollen auflisten: Listen Sie alle Grafana-Rollen auf, mit einem optionalen Filter für delegierbare Rollen.
  • Rolldetails abrufen: Rufen Sie Details für eine bestimmte Grafana-Rolle anhand der 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 Zuweisungsfunktionen für einen Ressourcentyp auf.

Navigation

  • Deeplinks generieren: Erstellen Sie präzise Deeplink-URLs für Grafana-Ressourcen, anstatt sich auf das Erraten von URLs durch LLMs 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 innerhalb von 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?left={"datasource":"prometheus-uid"})
    • Zeitbereichsunterstützung: Fügen Sie Zeitbereichsparameter zu Links hinzu (from=now-1h&to=now)
    • Benutzerdefinierte Parameter: Fügen Sie zusätzliche Abfrageparameter wie Dashboard-Variablen oder Aktualisierungsintervalle hinzu

Anmerkungen

  • Anmerkungen abrufen: Fragen Sie Anmerkungen mit Filtern ab. Unterstützt Zeitbereich, Dashboard-UID, Tags und Übereinstimmungsmodus.
  • Anmerkung erstellen: Erstellen Sie eine neue Anmerkung auf einem Dashboard oder Panel.
  • Graphite-Anmerkung erstellen: Erstellen Sie Anmerkungen im Graphite-Format (what, when, tags, data).
  • Anmerkung aktualisieren: Ersetzen Sie alle Felder einer vorhandenen Anmerkung (vollständige Aktualisierung).
  • Anmerkung patchen: Aktualisieren Sie nur bestimmte Felder einer Anmerkung (partielle Aktualisierung).
  • Anmerkungstags abrufen: Listen Sie verfügbare Anmerkungstags mit optionaler Filterung auf.

Schnappschüsse

  • Schnappschüsse auflisten: Listen Sie Dashboard-Schnappschüsse mit optionalen Abfrage- und Limitfiltern auf.
  • Schnappschuss abrufen: Rufen Sie Schnappschuss-Metadaten und Dashboard-Nutzdaten anhand des Schnappschussschlüssels ab.
  • Schnappschuss erstellen: Erstellen Sie einen Dashboard-Schnappschuss aus einem vollständigen Dashboard-Nutzdatenobjekt, mit optionalen Ablauf- und externen Schnappschussoptionen.
  • Schnappschuss löschen: Löschen Sie einen Schnappschuss anhand des Schnappschussschlü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, Zeitbereich, Thema, Skalierung und Dashboard-Variablen. Unterstützt auch das Rendern noch nicht angewendeter Dashboards aus einem Provisioning-Repository-Zweig (z. B. einer Git-Sync-PR-Vorschau) über den optionalen Parameter provisioningPreview.

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, Zweig, Pfad, Synchronisierungsstatus und Integrität zurück.
  • Provisionierungsdatei validieren: Führen Sie eine Trockenlauf-Anwendung einer Datei aus einem Provisioning-Repository bei einem bestimmten Zweig oder Commit durch. Gibt zurück, ob sie akzeptiert würde, die Ressourcenaktion (Erstellen/Aktualisieren), den Zielressourcentyp sowie alle strukturierten Validierungsfehler – dieselbe Validierungsoberflä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 den Kontextfenster nicht zu stark 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 bestimmte RBAC-Berechtigungen, um ordnungsgemäß zu funktionieren. Wenn Sie ein Dienstkonto für den MCP-Server erstellen, stellen Sie sicher, dass es über die erforderlichen Berechtigungen basierend auf den Tools verfügt, die Sie verwenden möchten. Die aufgeführten Berechtigungen sind die minimal erforderlichen Aktionen – möglicherweise benötigen Sie auch geeignete Bereiche (z. B. datasources:*, dashboards:*, folders:*), abhängig von Ihrem Anwendungsfall.

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

Hinweis: Grafana Incident- und Sift-Tools verwenden grundlegende Grafana-Rollen anstelle von fein granularen RBAC-Berechtigungen:

  • Viewer-Rolle: Erforderlich für schreibgeschützte Vorgänge (Vorfälle auflisten, Untersuchungen abrufen)
  • Editor-Rolle: Erforderlich für Schreibvorgänge (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 entsprechende 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 bestimmte UIDs oder IDs, um den Zugriff auf einzelne Ressourcen zu beschränken

    • datasources:uid:prometheus-uid – Zugriff nur auf eine bestimmte Prometheus-Datenquelle
    • dashboards:uid:abc123 – Zugriff nur auf 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: Gewähren 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 | Category | 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:* | | search_dashboards | Suche | Nach Dashboards suchen | dashboards:read | dashboards:* oder dashboards:uid:abc123 | | get_dashboard_by_uid | Dashboard | Ein Dashboard per UID abrufen | 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 | Titel, Abfragen, Datenquellen-UID und Typ eines Panels 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 nach 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 | Metrik-Metadaten 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 | Perzentilwerte für Histogramme berechnen | datasources:query | datasources:uid:prometheus-uid | | list_incidents | Vorfall | Vorfälle in Grafana Incident auflisten | Betrachter-Rolle | N/A | | create_incident | Vorfall | Ein Vorfall in Grafana Incident erstellen | Bearbeiter-Rolle | N/A | | add_activity_to_incident | Vorfall | Ein Aktivitätselement zu einem Vorfall in Grafana Incident hinzufügen | Bearbeiter-Rolle | N/A | | get_incident | Vorfall | Einen einzelnen Vorfall anhand der ID abrufen | Betrachter-Rolle | N/A | | query_loki_logs | Loki | Logs abfragen und abrufen mithilfe von LogQL (entweder Log- oder Metrikabfragen) | datasources:query | datasources:uid:loki-uid | | list_loki_label_names | Loki | Alle verfügbaren Labelnamen in Logs auflisten | datasources:query | datasources:uid:loki-uid | | list_loki_label_values | Loki | Werte für ein bestimmtes Log-Label auflisten | datasources:query | datasources:uid:loki-uid | | query_loki_stats | Loki | Statistiken zu Log-Streams abrufen | datasources:query | datasources:uid:loki-uid | | query_loki_patterns | Loki | Erkannte Logmuster abfragen, um gemeinsame Strukturen zu identifizieren | datasources:query | datasources:uid:loki-uid | | analyze_loki_labels | Loki | Eine Loki-Labelstrategie (live oder statisch) prüfen 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 erzwingt | N/A | N/A | | query_influxdb | InfluxDB | InfluxDB mit InfluxQL (v1) oder Flux (v2) abfragen | datasources:query | datasources:uid:influxdb-uid | | list_clickhouse_tables | ClickHouse* | Tabellen in einer ClickHouse-Datenbank auflisten | datasources:query | datasources:uid:* | | describe_clickhouse_table | ClickHouse* | Tabellenschema mit Spaltentypen abrufen | datasources:query | datasources:uid:* | | query_clickhouse | ClickHouse* | 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:* | | query_cloudwatch | CloudWatch* | CloudWatch-Metrikabfragen ausführen | datasources:query | datasources:uid:* | | list_athena_catalogs | Athena* | Verfügbare Athena-Datenkataloge auflisten | datasources:query | datasources:uid:* | | list_athena_databases | Athena* | Datenbanken in einem Athena-Katalog auflisten | datasources:query | datasources:uid:* | | list_athena_tables | Athena* | Tabellen in einer Athena-Datenbank auflisten | datasources:query | datasources:uid:* | | describe_athena_table | Athena* | Spaltennamen für eine Athena-Tabelle abrufen | datasources:query | datasources:uid:* | | query_athena | Athena* | SQL-Abfragen mit Makro-Substitution ausführen | 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 | | list_snowflake_tables | Snowflake* | Tabellen in einer Snowflake-Datenbank/einem Schema über INFORMATION_SCHEMA auflisten | datasources:query | datasources:uid:* | | describe_snowflake_table | Snowflake* | Tabellenschema abrufen (Spaltentypen, Nullbarkeit, Standardwerte, Kommentare) | datasources:query | datasources:uid:* | | query_snowflake | Snowflake* | SQL-Abfragen mit Makro-/Variablen-Substitution ausführen | datasources:query | datasources:uid:* | | alerting_manage_rules | Alerting | Alert-Regeln verwalten (auflisten, abrufen, Versionen, erstellen, aktualisieren, löschen) | alert.rules:read + alert.rules:write for mutations | folders:* or folders:uid:alerts-folder | | alerting_manage_routing | Alerting | Benachrichtigungsrichtlinien, Kontaktpunkte und Zeitintervalle verwalten | alert.notifications:read | Globaler Geltungsbereich | | list_oncall_schedules | OnCall | Zeitpläne von 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 Bereitschaft haben | grafana-oncall-app.schedules:read | Plugin-spezifische Geltungsbereiche | | list_oncall_teams | OnCall | Teams von Grafana OnCall auflisten | grafana-oncall-app.user-settings:read | Plugin-spezifische Geltungsbereiche | | list_oncall_users | OnCall | Benutzer von Grafana OnCall auflisten | grafana-oncall-app.user-settings:read | Plugin-spezifische Geltungsbereiche | | list_alert_groups | OnCall | Alert-Gruppen von Grafana OnCall mit Filteroptionen auflisten | grafana-oncall-app.alert-groups:read | Plugin-spezifische Geltungsbereiche | | get_alert_group | OnCall | Eine bestimmte Alert-Gruppe von Grafana OnCall anhand ihrer ID abrufen | grafana-oncall-app.alert-groups:read | Plugin-spezifische Geltungsbereiche | | get_sift_investigation | Sift | Eine vorhandene Sift-Untersuchung anhand ihrer UUID abrufen | Betrachterrolle | N/A | | get_sift_analysis | Sift | Eine bestimmte Analyse aus einer Sift-Untersuchung abrufen | Betrachterrolle | N/A | | list_sift_investigations | Sift | Eine Liste von Sift-Untersuchungen mit einem optionalen Limit abrufen | Betrachterrolle | N/A | | find_error_pattern_logs | Sift | Erkennt erhöhte Fehlermuster in Loki-Protokollen. | Bearbeiterrolle | N/A | | find_slow_requests | Sift | Erkennt langsame Anfragen aus den relevanten Tempo-Datenquellen. | Bearbeiterrolle | N/A | | 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 von Pyroscope abfragen | datasources:query | datasources:uid:pyroscope-uid | | get_assertions | Asserts | Assertion-Zusammenfassung für eine bestimmte Entität abrufen | Plugin-spezifische Berechtigungen | Plugin-spezifische Geltungsbereiche | | agento11y_manage_conversations | Agent Observability* | LLM-Konversationen von Grafana Agent Observability auflisten, durchsuchen und abrufen | grafana-agento11y-app.conversations:read | N/A | | agento11y_manage_generations | Agent Observability* | LLM-Generierungsdetails und Bewertungsergebnisse von Grafana Agent Observability abrufen | grafana-agento11y-app.data:read | N/A | | agento11y_manage_agents | Agent Observability* | Den Agent-Katalog lesen: Agenten auflisten, eine Agent-Version vollständig abrufen, Versionshistorie auflisten und aggregierte Bewertungen pro Version abrufen | grafana-agento11y-app.data:read | N/A | | agento11y_manage_evaluators | Agent Observability* | Evaluatoren, Evaluator-Vorlagen und den Judge-Katalog verwalten (auflisten, abrufen, upsert, forken, testen, löschen) | grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write for mutations and tests | N/A | | agento11y_manage_eval_rules | Agent Observability* | Eval-Regeln und Guards verwalten (auflisten, abrufen, erstellen, aktualisieren, Vorschau, löschen) | grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write for mutations and previews | 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 for mutations | 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 for mutations | N/A | | agento11y_manage_test_suites | Agent Observability* | Die Test-Suiten, gegen die Offline-Experimente laufen, ihre Versionen und ihre Testfälle verwalten (auflisten, abrufen, erstellen, aktualisieren, Entwurf, veröffentlichen, upsert, löschen) | grafana-agento11y-app.data:read + grafana-agento11y-app.eval:write for mutations | N/A | | ask_assistant | Assistant* | Eine Prompt an Grafana Assistant senden und die vollständige Textantwort zurückgeben (mehrere Runden über contextId) | Plugin-spezifische Berechtigungen | Plugin-spezifische Geltungsbereiche | | generate_deeplink | Navigation | Genaue Deeplink-URLs für Grafana-Ressourcen generieren | Keine (schreibgeschützte URL-Generierung) | N/A | | get_annotations | Annotations | Annotationen mit Filtern abrufen | annotations:read | annotations:* or annotations:id:123 | | create_annotation | Annotationen | Erstellen Sie eine neue Annotation (Standard- oder Graphite-Format) | annotations:write | annotations:* | | update_annotation | Annotationen | Aktualisieren Sie bestimmte Felder einer Annotation (partielle Aktualisierung) | annotations:write | annotations:* | | get_annotation_tags | Annotationen | Listen Sie Annotation-Tags mit optionaler Filterung auf | annotations:read | annotations:* | | list_snapshots | Schnappschuss | Listen Sie Dashboard-Schnappschüsse mit optionalen Abfrage- und Limit-Filtern auf | dashboards:read | dashboards:* or dashboards:uid:abc123 | | get_snapshot | Schnappschuss | Rufen Sie Snapshot-Metadaten und Dashboard-Payload anhand des Snapshot-Schlüssels ab | dashboards:read | dashboards:* or dashboards:uid:abc123 | | create_snapshot | Schnappschuss | Erstellen Sie einen Dashboard-Schnappschuss aus einem vollständigen Dashboard-Payload | dashboards:write | dashboards:* or dashboards:uid:abc123 | | delete_snapshot | Schnappschuss | Löschen Sie einen Dashboard-Schnappschuss anhand des Snapshot-Schlüssels | dashboards:write | dashboards:* or dashboards:uid:abc123 | | get_panel_image | Rendern | Rendern Sie ein gespeichertes Dashboard oder Panel — oder eine Bereitstellungsvorschau aus einem Repository-Zweig — als PNG-Bild | dashboards:read | dashboards:uid:abc123 | | list_provisioning_repositories | Bereitstellung | Listen Sie Bereitstellungs-Repositories (z. B. git-sync-Quellen) mit ihrer Quell-URL, Branch, Synchronisationsstatus und Gesundheitszustand auf | provisioning.repositories:read | N/A | | validate_provisioning_file | Bereitstellung | Wenden Sie eine Datei aus einem Bereitstellungs-Repository im Trockenlauf an und melden Sie Zulassungsvalidierungsfehler | provisioning.repositories:read | N/A | _* Standardmäßig deaktiviert. Fügen Sie die Kategorie zu --enabled-tools hinzu, um sie zu aktivieren.*

Referenz der CLI-Flags

Die mcp-grafana-Binärdatei unterstützt verschiedene Kommandozeilen-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
  • --endpoint-path: Endpunktpfad für den streamable-http-Server - Standard: /mcp
  • --server-name: Servername, der im MCP-Handshake und im OTel-service.name verwendet wird - Standard: mcp-grafana. Überschreibt die Umgebungsvariable GRAFANA_MCP_SERVER_NAME

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

Die Host/Origin-Validierung wird auf jeder Route des Listeners erzwungen – /sse, /mcp, /healthz und /metrics – sodass ein Browser mit DNS-Rebinding keine davon erreichen kann. Der Stdio-Transport ist davon nicht betroffen.

  • --allowed-hosts: Durch Kommas getrennte Zulassungsliste der Host-Header-Werte. 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, damit 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 Prüfung zu deaktivieren – nur sicher, wenn der Server hinter einem vertrauenswürdigen Reverse-Proxy läuft, der Host umschreibt, oder in einem isolierten Netzwerk. K8s-httpGet-Probes und externe /metrics-Scrapes benötigen entweder einen expliziten Hostnamen in dieser Liste, * oder eine tcpSocket-Probe / einen separaten Metrik-Port (--metrics-address).
  • --allowed-origins: Durch Kommas getrennte Zulassungsliste der Origin-Header-Werte. Standardmäßig leer – jede Anfrage, die einen Origin-Header trägt, wird abgelehnt (Browser senden bei Cross-Origin-Anfragen immer einen, 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.

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

Optional können MCP-Clients sich gegenüber dem Server authentifizieren müssen. Dies ist getrennt von den Anmeldedaten, die der Server verwendet, um Grafana zu erreichen. Stdio ist davon nicht betroffen.

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

Die Aufrufer-Authentifizierung wird nur durchgesetzt, 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-Logebene, damit er nicht durch --log-level verborgen wird (Loopback und Stdio sind nicht betroffen); eine zukünftige Hauptversion wird daraus einen Startfehler machen. Verwenden Sie TLS (oder TLS-Terminierung), wenn die Aufrufer-Authentifizierung auf einer Nicht-Loopback-Adresse aktiviert ist. Wenn die 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.

Debug und Protokollierung:

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

Grafana-Clientoptionen:

  • --grafana-timeout: Zeitlimit für Anfragen des Grafana-Clients. Akzeptiert Go-Dauer-Strings (z. B. 10s, 500ms) - Standard: 10s
  • --include-args-in-spans: Tool-Aufrufargumente in OpenTelemetry-Spans einbeziehen. Nur in Nicht-Produktionsumgebungen aktivieren oder wenn bekannt ist, dass die Argumente keine personenbezogenen Daten enthalten - Standard: false

Observability:

  • --metrics: Prometheus-Metrikendpunkt unter /metrics aktivieren
  • --metrics-address: Separate Adresse für den Metrik-Server (z. B. :9090). Wenn leer, werden Metriken auf dem Hauptserver bereitgestellt
  • --slow-request-threshold: Ein Ereignis protokollieren, wenn eine MCP-Anfrage (Tool-Aufruf, Auflistung, Ressourcenlesen usw.) länger als diese Dauer dauert. Akzeptiert Go-Dauer-Strings (z. B. 500ms, 5s). Standard 0 deaktiviert die Protokollierung langsamer Anfragen. Siehe Abschnitt Protokollierung langsamer Anfragen.
  • --slow-request-log-level: Protokollebene für Ereignisse langsamer Anfragen (info oder warn) - Standard: warn.

Sitzungsverwaltung:

  • --session-idle-timeout-minutes: Sitzungs-Idle-Timeout in Minuten. Sitzungen ohne Aktivität für diese Dauer werden automatisch beendet - Standard: 30. Setzen Sie 0, um das Beenden von Sitzungen zu deaktivieren. Nur für SSE- und streamable-http-Transporte relevant.

Tool-Konfiguration:

  • --enabled-tools: Durch Kommas getrennte Liste der aktivierten Kategorien - Standard: alle Kategorien außer admin, agento11y, assistant, athena, clickhouse, 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 Protokollzeilen, die pro query_loki_logs-Aufruf zurückgegeben werden - Standard: 100. Hinweis: Setzen Sie dies mindestens 1 unter dem serverseitigen max_entries_limit_per_query von Loki, um die Erkennung von Abschneidungen zu ermöglichen (das Tool fordert limit+1 intern an, um zu erkennen, ob weitere Daten vorhanden sind).
  • --disable-search: Suchtools deaktivieren
  • --disable-datasource: Datasource-Tools deaktivieren
  • --disable-incident: Incident-Tools deaktivieren
  • --disable-prometheus: Prometheus-Tools deaktivieren
  • --disable-write: Schreibtools deaktivieren (Erstellungs-/Aktualisierungsvorgänge)
  • --disable-loki: Loki-Tools deaktivieren
  • --disable-elasticsearch: Elasticsearch- und OpenSearch-Tools deaktivieren
  • --disable-quickwit: Quickwit-Tools deaktivieren
  • --disable-influxdb: InfluxDB-Tools deaktivieren
  • --disable-alerting: Alarmierungstools deaktivieren
  • --disable-dashboard: Dashboard-Tools deaktivieren
  • --disable-oncall: OnCall-Tools deaktivieren
  • --disable-asserts: Asserts-Tools deaktivieren
  • --disable-sift: Sift-Tools deaktivieren
  • --disable-admin: Admin-Tools deaktivieren
  • --disable-pyroscope: Pyroscope-Tools deaktivieren
  • --disable-navigation: Navigationstools deaktivieren
  • --disable-rendering: Rendering-Tools deaktivieren (Panel-/Dashboard-Bildexport)
  • --disable-snapshot: Snapshot-Tools deaktivieren
  • --disable-cloudwatch: CloudWatch-Tools deaktivieren
  • --disable-examples: Abfragebeispiel-Tools deaktivieren
  • --disable-clickhouse: ClickHouse-Tools deaktivieren
  • --disable-snowflake: Snowflake-Tools deaktivieren
  • --disable-runpanelquery: Panel-Abfrage-Tools deaktivieren
  • --disable-graphite: Graphite-Tools deaktivieren
  • --disable-athena: Athena-Tools deaktivieren
  • --disable-provisioning: Provisioning-Tools deaktivieren
  • --disable-agento11y: Agent-Observability-Tools deaktivieren
  • --disable-assistant: Grafana-Assistant-Tools deaktivieren

Nur-Lese-Modus

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

  • Verwendung von Servicekonten mit eingeschränkten Nur-Lese-Berechtigungen
  • Bereitstellung von Observability-Daten 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, werden die folgenden Schreibvorgänge deaktiviert:

Dashboard-Tools:

  • update_dashboard

Ordner-Tools:

  • create_folder

Incident-Tools:

  • create_incident
  • add_activity_to_incident

Alarmierungstools:

  • alerting_manage_rules (Erstellungs-, Aktualisierungs- und Löschvorgänge)

Annotationstools:

  • create_annotation
  • update_annotation

Sift-Tools:

  • find_error_pattern_logs (erstellt Untersuchungen)
  • find_slow_requests (erstellt Untersuchungen)

Snapshot-Tools:

  • create_snapshot
  • delete_snapshot

Agent-Observability-Tools:

  • agento11y_manage_evaluators (Upsert-, Lösch-, Fork- und 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 Konversationen; Erstellen, Aktualisieren und 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.

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. Verwenden Sie für Grafana Cloud Ihre Instanz-URL (z. B. https://myinstance.grafana.net) anstelle von http://localhost:3000 in den folgenden Konfigurationsbeispielen.

  1. Wenn Sie die Servicekonto-Token-Authentifizierung verwenden, erstellen Sie ein Servicekonto in Grafana mit ausreichenden Berechtigungen für die Tools, die Sie verwenden möchten, generieren Sie ein Servicekonto-Token und kopieren Sie es für die Verwendung in der Konfigurationsdatei in die Zwischenablage. Weitere Einzelheiten zum Erstellen von Servicekonto-Tokens finden Sie in der Grafana-Servicekonto-Dokumentation. Tipp: Wenn Sie sich nicht wohl dabei fühlen, fein granulierte RBAC-Bereiche zu konfigurieren, besteht eine einfachere (aber weniger restriktive) Option darin, dem Servicekonto die integrierte Rolle Editor zuzuweisen. Diese gewährt umfassenden Lese-/Schreibzugriff, der die meisten MCP-Servervorgänge abdeckt – verwenden Sie sie, wenn Bequemlichkeit wichtiger ist als strenge Least-Privilege-Anforderungen.

    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 aus Gründen der Abwärtskompatibilität, zeigt jedoch Veraltungswarnungen an.

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 zeigen, der das Token enthält. Die Datei wird bei jeder Anfrage frisch gelesen, sodass rotierte Tokens automatisch ohne Neustart des Servers übernommen werden.

Dies ist besonders in Kubernetes nützlich, wo ein als Volume gemountetes Secret an Ort und Stelle aktualisiert wird, wenn sich das zugrunde liegende Secret ändert (normalerweise innerhalb von ca. 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 Ausfallzeiten:

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

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

Unterstützung mehrerer Organisationen

Sie können 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 SSE- oder streamable-HTTP-Transporte verwenden (Header hat Vorrang vor der Umgebungsvariable – Sie können also auch eine Standard-Organisation festlegen).

Wenn eine Organisations-ID angegeben wird, setzt der MCP-Server den X-Grafana-Org-Id-Header auf alle Anfragen an Grafana, sodass sichergestellt ist, dass Vorgänge im Kontext der angegebenen Organisation ausgeführt werden.

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

Weiterleitung von Headern vom Client (nur SSE/Streamable-HTTP)

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

Dies gilt nur bei Verwendung von SSE (-t sse) oder Streamable-HTTP (-t streamable-http) Transporten. Im Stdio-Modus hat es keine Wirkung.

Beispiel: Sitzungscookie weiterleiten

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

Sie können mehrere Header weiterleiten, indem Sie sie mit 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.

  1. Sie haben mehrere Optionen, um mcp-grafana zu installieren:

    • uvx (empfohlen): Wenn Sie uv installiert haben, ist keine zusätzliche Einrichtung erforderlich — uvx wird den Server automatisch herunterladen und ausführen:

      uvx mcp-grafana

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

      Wichtig: Der Einstiegspunkt des Docker-Images ist so konfiguriert, dass der MCP-Server standardmäßig im SSE-Modus läuft, 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 Flag -i einfügen, 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: Im SSE- und Streamable-HTTP-Modus bindet der Container eine Nicht-Loopback-Adresse (0.0.0.0:8000). Ohne einen Aufrufer-Token startet der Server startet, protokolliert jedoch einen Sicherheitsfehler (auf der Protokollebene error, sodass er nicht durch --log-level verborgen wird; und er wird sich in einer zukünftigen Hauptversion weigern 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 Aufrufer-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 Flag -p freigeben:
      docker pull grafana/mcp-grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
      1. Streamable-HTTP-Modus: In diesem Modus arbeitet der Server als unabhängiger Prozess, der mehrere Client-Verbindungen verarbeiten kann. Sie müssen Port 8000 mit dem Flag -p 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 Release-Seite herunter und legen Sie sie in Ihrem $PATH ab.

    • 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/cmd/mcp-grafana@latest

    • Bereitstellung auf Kubernetes mit Helm: Verwenden Sie das Helm-Chart aus dem Grafana-Helm-Charts-Repository

      helm repo add grafana https://grafana.github.io/helm-charts
helm install --set grafana.apiKey=<Grafana_ApiKey> --set grafana.url=<GrafanaUrl> my-release grafana/grafana-mcp

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

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

Verwendung 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 Flag -debug 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 Argument -t stdio 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 Serverüberprüfung
  • --tls-skip-verify: TLS-Zertifikatsprüfung ü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-Datenquellen-Clients
  • Loki-Datenquellen-Clients
  • Incident-Management-Clients
  • Sift-Untersuchungs-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

Nur mit 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 eine erreichbare Panik 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
  • Text: ok

Beispielverwendung:

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

# With custom address
curl http://localhost:9090/healthz

Hinweis: Der Health-Check-Endpunkt ist nur bei Verwendung von SSE- oder Streamable-HTTP-Transporten verfügbar. Er ist nicht verfügbar, wenn der Stdio-Transport (-t stdio) verwendet wird, da Stdio keinen HTTP-Server bereitstellt.

Beobachtbarkeit

Der MCP-Server unterstützt Prometheus-Metriken, OpenTelemetry-verteiltes Tracing und OpenTelemetry-Log-Export gemäß den OTel-MCP-semantischen Konventionen. 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 für sowohl Traces als auch 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-Transporte aktivieren Sie Prometheus-Metriken mit dem Flag --metrics:

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

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

Verfügbare Metriken:

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

Hinweis: Metriken sind nur bei Verwendung von SSE- oder Streamable-HTTP-Transporten verfügbar. Sie sind nicht mit dem Stdio-Transport verfügbar.

Protokollierung langsamer Anfragen

Das Flag --slow-request-threshold gibt ein strukturiertes Log-Ereignis aus, wenn eine MCP-Anfrage (Tool-Aufruf, Liste, Ressourcenlesen usw.) die angegebene Dauer überschreitet. Es ist nützlich, um langsame Abfragen und Tool-Aufrufe zu diagnostizieren, 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:

AttributBeschreibung
mcp.methodDie MCP-Methode (z. B. tools/call, tools/list, resources/read)
durationBeobachtete Anfragedauer
thresholdKonfigurierter Schwellenwert
toolTool-Name (nur für tools/call-Methoden vorhanden)
errorFehlerwert, wenn die Anfrage fehlgeschlagen ist (Best-Effort-Kontext; Inhalt wird durch das Upstream-Fehler-Wrapping gesteuert)
error.typeFehlerklassifizierung mit begrenzter Kardinalität (_OTHER für untypisierte Fehler)

Die Protokollierung langsamer Anfragen funktioniert auf allen Transporten (einschließlich Stdio) und erfordert kein --metrics. Der Standard-Schwellenwert von 0 deaktiviert sie vollständig. Proxierte Tools laufen über tools/call und werden automatisch abgedeckt.

Tracing

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

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

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

Tool-Aufruf-Spans folgen der Semconv-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-Kontextausbreitung aus dem _meta-Feld von Tool-Aufruf-Anfragen.

Logs

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

Traces und Logs lösen ihre Endpunkte unabhängig auf, sodass die beiden Signale separat aktiviert werden können: Das Setzen nur von OTEL_EXPORTER_OTLP_TRACES_ENDPOINT aktiviert Tracing ohne Log-Export, das Setzen nur von OTEL_EXPORTER_OTLP_LOGS_ENDPOINT 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. wenn Ihr Backend das LogsService nicht unterstützt), setzen Sie:

OTEL_LOGS_EXPORTER=none

Dies verhindert, dass der Server unabhängig von der Endpunkt-Konfiguration 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 an /dev/null weiterleiten, wenn Sie das bevorzugen.

# 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 – zum Beispiel Grafana Cloud –, indem OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (oder das generische OTEL_EXPORTER_OTLP_ENDPOINT) auf den entfernten gRPC-Endpunkt zeigt und die Authentifizierung über OTEL_EXPORTER_OTLP_LOGS_HEADERS (oder OTEL_EXPORTER_OTLP_HEADERS) erfolgt, analog zum obigen Tracing-Beispiel. Ein lokaler OTel-Collector ist optional – nützlich für Fan-out, Batching oder Multi-Backend-Routing, aber nicht erforderlich.

Die signal-spezifischen 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 die Vorrangregeln.

Wenn der konfigurierte Collector nicht erreichbar ist, werden Log-Einträge im Speicher gepuffert (Standard-Warteschlange: 2048) und die ältesten Einträge 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 während Ausfällen eine verlustfreie Pufferung benötigen.

Logs werden auch über den stdio-Transport exportiert, was es einfach macht, Logs von lokalen mcp-grafana-Instanzen zu zentralisieren, 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

Fehlerbehebung

Grafana-Versionskompatibilität

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

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

Dies deutet in der Regel 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 Datenquellen-Operationen 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 eröffnen Sie ein Issue oder reichen Sie einen Pull-Request ein, wenn Sie Vorschläge oder Verbesserungen haben.

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 selbst erstellten Docker-Image ausführen. Wie beim veröffentlichten Docker-Image ist der Entrypoint dieses benutzerdefinierten Images standardmäßig auf den SSE-Modus eingestellt. 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 Transport-Einstellung:

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

Testen

Es stehen drei Arten von Tests zur Verfügung:

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

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

make test
  1. Integrationstests (erfordert laufende Docker-Container):
make test-integration
  1. Cloud-Tests (erfordert eine Cloud-Grafana-Instanz und Anmeldedaten):
make test-cloud

Hinweis: Cloud-Tests werden automatisch in CI 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 stilles Abschneiden 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 License, Version 2.0 lizenziert.