Grafana

offiziell

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

GitHub
3.2k

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). Siehe Verwendung für weitere Installationsoptionen einschließlich Docker, Binary und Helm.

Anforderungen

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

Funktionen

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

Dashboards

  • Nach Dashboards suchen: Dashboards anhand des Titels oder anderer Metadaten finden
  • Dashboard per UID abrufen: Vollständige Dashboard-Details anhand seiner eindeutigen Kennung abrufen. Warnung: Große Dashboards können erheblichen Kontextfenster-Speicherplatz beanspruchen.
  • 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 Kontextfenster-Nutzung 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 Kontextfenster-Verbrauch zu reduzieren
  • Dashboard aktualisieren oder erstellen: Vorhandene Dashboards ändern oder neue erstellen. Warnung: Erfordert vollständiges Dashboard-JSON, was große Mengen an Kontextfenster-Speicherplatz beanspruchen kann.
  • Dashboard patchen: Gezielte Änderungen an einem Dashboard vornehmen, ohne das vollständige JSON zu benötigen, wodurch die Kontextfenster-Nutzung für gezielte Modifikationen erheblich reduziert wird
  • Panel-Abfragen und Datenquellen-Info 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: Werkzeuge 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: Eine Dashboard-Panel-Abfrage mit benutzerdefinierten Zeitbereichen und Variablenüberschreibungen ausführen.

Kontextfenster-Verwaltung

Die Dashboard-Werkzeuge enthalten jetzt mehrere Strategien zur effektiven Verwaltung der Kontextfenster-Nutzung (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 abrufen.
    • Unterstützte Datenquellentypen: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Abfragebeispiele

Hinweis: Werkzeuge 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 Instant- als auch Range-Metrikabfragen) für Prometheus-Datenquellen ausführen.
  • Prometheus-Metadaten abfragen: Metrik-Metadaten, Metriknamen, Label-Namen und Label-Werte von Prometheus-Datenquellen abrufen.
  • Histogramm-Perzentile abfragen: Histogramm-Perzentilwerte (p50, p90, p95, p99) mit histogram_quantile berechnen.

Loki-Abfragen

  • Loki-Logs und -Metriken abfragen: Sowohl Log- als auch Metrikabfragen mit LogQL für Loki-Datenquellen ausführen.
  • Loki-Metadaten abfragen: Label-Namen, Label-Werte und Stream-Statistiken von Loki-Datenquellen abrufen.
  • Loki-Muster abfragen: Von Loki erkannte Log-Muster abrufen, um gängige Log-Strukturen und Anomalien zu identifizieren.

InfluxDB-Abfragen

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

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

ClickHouse-Abfragen

Hinweis: ClickHouse-Werkzeuge 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öße auflisten.
  • Tabellenschema beschreiben: Spaltennamen, Typen und Metadaten für eine ClickHouse-Tabelle abrufen.
  • ClickHouse abfragen: SQL-Abfragen mit Unterstützung für Grafana-Makro- und Variablenersetzung ausführen.

CloudWatch-Abfragen

Hinweis: CloudWatch-Werkzeuge 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 Zeitbereichsunterstützung ausführen.

Graphite-Abfragen

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

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

Athena-Abfragen

Hinweis: Athena-Werkzeuge 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-Konnektoren).
  • 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 für Amazon Athena über Grafana mit Makroersetzung, Limit-Durchsetzung und Vorlagenvariablen-Unterstützung ausführen.

Snowflake-Abfragen

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

Abfragen gehen über die Snowflake-Datenquelle von Grafana (Grafana Enterprise Plugin grafana-snowflake-datasource), sodass die Authentifizierung von der Datenquellenkonfiguration in Grafana übernommen wird – Anmeldeinformationen werden vom MCP-Server niemals eingesehen. Dies ist dasselbe Modell, das für die ClickHouse-Werkzeuge verwendet wird.

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

Elasticsearch/OpenSearch-Abfragen

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

  • Elasticsearch/OpenSearch abfragen: Suchabfragen für Elasticsearch- oder OpenSearch-Datenquellen mit Lucene-Abfragesyntax oder Elasticsearch Query DSL ausführen. Unterstützt Filterung nach Zeitbereich und Abrufen von Logs, Metriken oder beliebigen indizierten Daten. Gibt Dokumente mit ihrem Index, ihrer ID, Quellfeldern und optionalem Relevanzwert zurück.

Quickwit-Abfragen

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

  • Quickwit abfragen: Suchabfragen für Quickwit-Datenquellen mit Lucene-Abfragesyntax oder partieller Elasticsearch-kompatibler Query DSL ausführen. Unterstützt Filterung nach Zeitbereich und Abrufen von Logs oder anderen indizierten Dokumenten. Gibt Dokumente mit ihrem Index, ihrer ID, Quellfeldern und optionalem Relevanzwert zurück.

Vorfälle

  • Vorfälle suchen, erstellen und aktualisieren: Vorfälle in Grafana Incident verwalten, einschließlich Suchen, Erstellen und Hinzufügen von Aktivitäten zu Vorfällen.

Sift-Untersuchungen

  • Sift-Untersuchungen auflisten: Eine Liste der Sift-Untersuchungen abrufen, mit Unterstützung für einen Limit-Parameter.
  • Sift-Untersuchung abrufen: Details einer bestimmten Sift-Untersuchung anhand ihrer UUID abrufen.
  • Sift-Analysen abrufen: Eine bestimmte Analyse aus einer Sift-Untersuchung abrufen.
  • Fehlermuster in Logs finden: Erhöhte Fehlermuster in Loki-Logs mit Sift erkennen.
  • Langsame Anfragen finden: Langsame Anfragen mit Sift (Tempo) erkennen.

Alarmierung

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

Grafana OnCall

  • Bereitschaftspläne auflisten und verwalten: Bereitschaftspläne in Grafana OnCall anzeigen und verwalten.
  • Schichtdetails abrufen: Detaillierte Informationen zu bestimmten Bereitschaftsschichten abrufen.
  • Aktuelle Bereitschaftsbenutzer abrufen: Anzeigen, welche Benutzer derzeit für einen Plan bereit sind.
  • Teams und Benutzer auflisten: Alle OnCall-Teams und -Benutzer anzeigen.
  • Alarmgruppen auflisten: Alarmgruppen von Grafana OnCall nach verschiedenen Kriterien wie Status, Integration, Labels und Zeitbereich anzeigen und filtern.
  • Alarmgruppendetails abrufen: Detaillierte Informationen zu einer bestimmten Alarmgruppe anhand ihrer ID abrufen.

Administration

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

  • Teams auflisten: Alle konfigurierten Teams in Grafana anzeigen.
  • Benutzer auflisten: Alle Benutzer in einer Organisation in Grafana anzeigen.
  • Alle Rollen auflisten: Alle Grafana-Rollen auflisten, mit einem optionalen Filter für delegierbare Rollen.
  • Rollendetails abrufen: Details für eine bestimmte Grafana-Rolle anhand der UID abrufen.
  • Zuweisungen für eine Rolle auflisten: Alle Benutzer, Teams und Dienstkonten auflisten, die einer Rolle zugewiesen sind.
  • Rollen für Benutzer auflisten: Alle Rollen auflisten, die einem oder mehreren Benutzern zugewiesen sind.
  • Rollen für Teams auflisten: Alle Rollen auflisten, die einem oder mehreren Teams zugewiesen sind.
  • Berechtigungen für eine Ressource auflisten: Alle für eine bestimmte Ressource definierten Berechtigungen auflisten (Dashboard, Datenquelle, Ordner usw.).
  • Eine Grafana-Ressource beschreiben: Verfügbare Berechtigungen und Zuweisungsmöglichkeiten für einen Ressourcentyp auflisten.

Navigation

  • Deep-Links generieren: Erstellen Sie präzise Deep-Link-URLs für Grafana-Ressourcen, anstatt sich auf URL-Raten durch das LLM zu verlassen.
    • Dashboard-Links: Generieren Sie direkte Links zu Dashboards anhand 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"})
    • Zeitraum-Unterstützung: Fügen Sie Zeitraum-Parameter zu Links hinzu (from=now-1h&to=now)
    • Benutzerdefinierte Parameter: Schließen Sie zusätzliche Abfrageparameter wie Dashboard-Variablen oder Aktualisierungsintervalle ein

Annotationen

  • Annotationen abrufen: Annotationen mit Filtern abfragen. Unterstützt Zeitraum, Dashboard-UID, Tags und Übereinstimmungsmodus.
  • Annotation erstellen: Eine neue Annotation in einem Dashboard oder Panel erstellen.
  • Graphite-Annotation erstellen: Annotationen im Graphite-Format erstellen (what, when, tags, data).
  • Annotation aktualisieren: Alle Felder einer bestehenden Annotation ersetzen (vollständige Aktualisierung).
  • Annotation patchen: Nur bestimmte Felder einer Annotation aktualisieren (teilweise Aktualisierung).
  • Annotation-Tags abrufen: Verfügbare Annotation-Tags mit optionaler Filterung auflisten.

Snapshots

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

Rendering

  • Panel- oder Dashboard-Bild abrufen: Ein Grafana-Dashboard-Panel oder ein vollständiges Dashboard als PNG-Bild rendern. Gibt das Bild als base64-kodierte Daten zur Verwendung in Berichten, Warnmeldungen 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-Branch (z. B. eine Git-Sync-PR-Vorschau) über den optionalen Parameter provisioningPreview.

Provisionierung

  • Provisioning-Repositories auflisten: Für diese Grafana-Instanz konfigurierte Provisioning-Repositories auflisten (z. B. Git-Sync-Quellen) und den Slug jedes Repositorys zusammen mit seiner Quell-URL, Branch, Pfad, Synchronisierungsstatus und Integrität zurückgeben.
  • Provisioning-Datei validieren: Eine Datei aus einem Provisioning-Repository bei einem bestimmten Branch oder Commit probehalber anwenden. Gibt zurück, ob sie akzeptiert würde, die Ressourcenaktion (Erstellen/Aktualisieren), den Zielressourcentyp und alle strukturierten Validierungsfehler – dieselbe Zulassungsoberfläche, die der Grafana-PR-Kommentator verwendet.

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

RBAC-Berechtigungen

Jedes Werkzeug benötigt spezifische RBAC-Berechtigungen, um ordnungsgemäß zu funktionieren. Stellen Sie beim Erstellen eines Dienstkontos für den MCP-Server sicher, dass es über die erforderlichen Berechtigungen verfügt, basierend darauf, welche Werkzeuge Sie verwenden möchten. Die aufgeführten Berechtigungen sind die mindestens erforderlichen Aktionen – je nach Anwendungsfall benötigen Sie möglicherweise auch entsprechende Geltungsbereiche (z. B. datasources:*, dashboards:*, folders:*).

Tipp: Wenn Sie mit Grafana RBAC nicht vertraut sind oder ein schnelleres, einfacheres Setup anstelle der Konfiguration vieler granularer Geltungsbereiche 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-Server-Operationen ermöglicht; sie ist weniger granular (und daher weniger restriktiv) als manuell angewendete Geltungsbereiche, verwenden Sie sie daher nur, wenn Bequemlichkeit wichtiger ist als ein strikter Zugriff mit minimalen Rechten.

Hinweis: Grafana Incident- und Sift-Werkzeuge verwenden grundlegende Grafana-Rollen anstelle von feingranularen 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-Geltungsbereiche

Geltungsbereiche definieren die spezifischen Ressourcen, für die Berechtigungen gelten. Jede Aktion erfordert sowohl die entsprechende Berechtigung als auch die passende Geltungsbereichskombination.

Gängige Geltungsbereichsmuster:

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

Beispiele:

  • Voller MCP-Server-Zugriff: Gewähren Sie umfassende Berechtigungen für alle Werkzeuge

    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)

Werkzeuge

ToolKategorieBeschreibungErforderliche RBAC-BerechtigungenErforderliche Scopes
list_teamsAdminAlle Teams auflistenteams:readteams:* oder teams:id:1
list_users_by_orgAdminAlle Benutzer einer Organisation auflistenusers:readglobal.users:* oder global.users:id:123
list_all_rolesAdminAlle Grafana-Rollen auflistenroles:readroles:*
get_role_detailsAdminDetails zu einer Grafana-Rolle abrufenroles:readroles:uid:editor
get_role_assignmentsAdminZuweisungen für eine Rolle auflistenroles:readroles:uid:editor
list_user_rolesAdminRollen für Benutzer auflistenroles:readglobal.users:id:123
list_team_rolesAdminRollen für Teams auflistenroles:readteams:id:7
get_resource_permissionsAdminBerechtigungen für eine Ressource auflistenpermissions:readdashboards:uid:abcd1234
get_resource_descriptionAdminEinen Grafana-Ressourcentyp beschreibenpermissions:readdashboards:*
search_dashboardsSucheNach Dashboards suchendashboards:readdashboards:* oder dashboards:uid:abc123
get_dashboard_by_uidDashboardEin Dashboard anhand der UID abrufendashboards:readdashboards:uid:abc123
update_dashboardDashboardEin Dashboard aktualisieren oder neu erstellendashboards:create, dashboards:writedashboards:*, folders:* oder folders:uid:xyz789
get_dashboard_panel_queriesDashboardPanel-Titel, Abfragen, Datenquellen-UID und -Typ aus einem Dashboard abrufendashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*Eine oder mehrere Dashboard-Panel-Abfragen ausführendashboards:read, datasources:querydashboards:uid:*, datasources:uid:*
get_dashboard_propertyDashboardBestimmte Teile eines Dashboards mit JSONPath-Ausdrücken extrahierendashboards:readdashboards:uid:abc123
get_dashboard_summaryDashboardEine kompakte Zusammenfassung eines Dashboards ohne vollständiges JSON abrufendashboards:readdashboards:uid:abc123
list_datasourcesDatenquellenDatenquellen auflistendatasources:readdatasources:*
get_datasourceDatenquellenEine Datenquelle anhand von UID oder Name abrufendatasources:readdatasources:uid:prometheus-uid
get_query_examplesBeispiele*Beispielabfragen für einen Datenquellentyp abrufendatasources:readdatasources:*
query_prometheusPrometheusEine Abfrage gegen eine Prometheus-Datenquelle ausführendatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_metadataPrometheusMetadaten zu Metriken auflistendatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusVerfügbare Metriknamen auflistendatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusLabel-Namen auflisten, die einem Selektor entsprechendatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusWerte für ein bestimmtes Label auflistendatasources:querydatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusPerzentilwerte für Histogramme berechnendatasources:querydatasources:uid:prometheus-uid
list_incidentsIncidentVorfälle in Grafana Incident auflistenViewer-RolleN/A
create_incidentIncidentEinen Vorfall in Grafana Incident erstellenEditor-RolleN/A
add_activity_to_incidentIncidentEinem Vorfall in Grafana Incident ein Aktivitätselement hinzufügenEditor-RolleN/A
get_incidentIncidentEinen einzelnen Vorfall anhand der ID abrufenViewer-RolleN/A
query_loki_logsLokiProtokolle mit LogQL abfragen und abrufen (entweder Log- oder Metrikabfragen)datasources:querydatasources:uid:loki-uid
list_loki_label_namesLokiAlle verfügbaren Label-Namen in Protokollen auflistendatasources:querydatasources:uid:loki-uid
list_loki_label_valuesLokiWerte für ein bestimmtes Protokoll-Label auflistendatasources:querydatasources:uid:loki-uid
query_loki_statsLokiStatistiken über Protokollströme abrufendatasources:querydatasources:uid:loki-uid
query_loki_patternsLokiErkannte Protokollmuster abfragen, um gemeinsame Strukturen zu identifizierendatasources:querydatasources:uid:loki-uid
analyze_loki_labelsLokiEine Loki-Label-Strategie prüfen (live oder statisch) und optional die Abfrageleistung diagnostizierendatasources:querydatasources:uid:loki-uid
suggest_loki_alloy_label_configKonfigurationEin Alloy-loki.process-Snippet generieren, das genehmigte Labels erzwingtN/AN/A
query_influxdbInfluxDBInfluxDB mit InfluxQL (v1) oder Flux (v2) abfragendatasources:querydatasources:uid:influxdb-uid
list_clickhouse_tablesClickHouse*Tabellen in einer ClickHouse-Datenbank auflistendatasources:querydatasources:uid:*
describe_clickhouse_tableClickHouse*Tabellenschema mit Spaltentypen abrufendatasources:querydatasources:uid:*
query_clickhouseClickHouse*SQL-Abfragen mit Makrosubstitution ausführendatasources:querydatasources:uid:*
list_cloudwatch_namespacesCloudWatch*Verfügbare AWS-CloudWatch-Namespaces auflistendatasources:querydatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*Dimensionen für eine Metrik auflistendatasources:querydatasources:uid:*
query_cloudwatchCloudWatch*CloudWatch-Metrikabfragen ausführendatasources:querydatasources:uid:*
list_athena_catalogsAthena*Verfügbare Athena-Datenkataloge auflistendatasources:querydatasources:uid:*
list_athena_databasesAthena*Datenbanken in einem Athena-Katalog auflistendatasources:querydatasources:uid:*
list_athena_tablesAthena*Tabellen in einer Athena-Datenbank auflistendatasources:querydatasources:uid:*
describe_athena_tableAthena*Spaltennamen für eine Athena-Tabelle abrufendatasources:querydatasources:uid:*
query_athenaAthena*SQL-Abfragen mit Makroersetzung ausführendatasources:querydatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*Elasticsearch oder OpenSearch mit Lucene-Syntax oder Query DSL abfragendatasources:querydatasources:uid:datasource-uid
query_quickwitQuickwit*Quickwit mit Lucene-Syntax oder Query DSL abfragendatasources:querydatasources:uid:quickwit-uid
list_snowflake_tablesSnowflake*Tabellen in einer Snowflake-Datenbank/-Schema über INFORMATION_SCHEMA auflistendatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*Tabellenschema abrufen (Spaltentypen, Nullierbarkeit, Standardwerte, Kommentare)datasources:querydatasources:uid:*
query_snowflakeSnowflake*SQL-Abfragen mit Makro-/Variablenersetzung ausführendatasources:querydatasources:uid:*
alerting_manage_rulesAlarmierungAlarmregeln verwalten (auflisten, abrufen, Versionen, erstellen, aktualisieren, löschen)alert.rules:read + alert.rules:write für Mutationenfolders:* oder folders:uid:alerts-folder
alerting_manage_routingAlarmierungBenachrichtigungsrichtlinien, Kontaktpunkte und Zeitintervalle verwaltenalert.notifications:readGlobaler Geltungsbereich
list_oncall_schedulesOnCallBereitschaftspläne aus Grafana OnCall auflistengrafana-oncall-app.schedules:readPlugin-spezifische Geltungsbereiche
get_oncall_shiftOnCallDetails für eine bestimmte OnCall-Schicht abrufengrafana-oncall-app.schedules:readPlugin-spezifische Geltungsbereiche
get_current_oncall_usersOnCallDerzeit für einen bestimmten Plan bereite Benutzer abrufengrafana-oncall-app.schedules:readPlugin-spezifische Geltungsbereiche
list_oncall_teamsOnCallTeams aus Grafana OnCall auflistengrafana-oncall-app.user-settings:readPlugin-spezifische Geltungsbereiche
list_oncall_usersOnCallBenutzer aus Grafana OnCall auflistengrafana-oncall-app.user-settings:readPlugin-spezifische Geltungsbereiche
list_alert_groupsOnCallAlarmgruppen aus Grafana OnCall mit Filteroptionen auflistengrafana-oncall-app.alert-groups:readPlugin-spezifische Geltungsbereiche
get_alert_groupOnCallEine bestimmte Alarmgruppe aus Grafana OnCall anhand ihrer ID abrufengrafana-oncall-app.alert-groups:readPlugin-spezifische Geltungsbereiche
get_sift_investigationSiftEine bestehende Sift-Untersuchung anhand ihrer UUID abrufenBetrachter-RolleN/A
get_sift_analysisSiftEine bestimmte Analyse aus einer Sift-Untersuchung abrufenBetrachter-RolleN/A
list_sift_investigationsSiftEine Liste von Sift-Untersuchungen mit optionalem Limit abrufenBetrachter-RolleN/A
find_error_pattern_logsSiftErhöhte Fehlermuster in Loki-Logs finden.Bearbeiter-RolleN/A
find_slow_requestsSiftLangsame Anfragen aus den relevanten Tempo-Datenquellen finden.Bearbeiter-RolleN/A
list_pyroscope_label_namesPyroscopeLabel-Namen auflisten, die einem Selektor entsprechendatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeLabel-Werte auflisten, die einem Selektor für einen Label-Namen entsprechendatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeVerfügbare Profiltypen auflistendatasources:querydatasources:uid:pyroscope-uid
query_pyroscopePyroscopeProfile, Metriken oder beides von Pyroscope abfragendatasources:querydatasources:uid:pyroscope-uid
get_assertionsAssertsAssertion-Zusammenfassung für eine bestimmte Entität abrufenPlugin-spezifische BerechtigungenPlugin-spezifische Geltungsbereiche
generate_deeplinkNavigationPräzise Deeplink-URLs für Grafana-Ressourcen generierenKeine (schreibgeschützte URL-Generierung)N/A
get_annotationsAnnotationenAnnotationen mit Filtern abrufenannotations:readannotations:* oder annotations:id:123
create_annotationAnnotationenNeue Annotation erstellen (Standard- oder Graphite-Format)annotations:writeannotations:*
update_annotationAnnotationenBestimmte Felder einer Annotation aktualisieren (Teilaktualisierung)annotations:writeannotations:*
get_annotation_tagsAnnotationenAnnotation-Tags mit optionaler Filterung auflistenannotations:readannotations:*
list_snapshotsSnapshotDashboard-Snapshots mit optionalen Abfrage- und Limit-Filtern auflistendashboards:readdashboards:* oder dashboards:uid:abc123
get_snapshotSnapshotSnapshot-Metadaten und Dashboard-Payload anhand des Snapshot-Schlüssels abrufendashboards:readdashboards:* oder dashboards:uid:abc123
create_snapshotSnapshotDashboard-Snapshot aus einem vollständigen Dashboard-Payload erstellendashboards:writedashboards:* oder dashboards:uid:abc123
delete_snapshotSnapshotDashboard-Snapshot anhand des Snapshot-Schlüssels löschendashboards:writedashboards:* oder dashboards:uid:abc123
get_panel_imageRenderingEin gespeichertes Dashboard oder Panel – oder eine Bereitstellungsvorschau aus einem Repository-Branch – als PNG-Bild renderndashboards:readdashboards:uid:abc123
list_provisioning_repositoriesProvisionierungBereitstellungs-Repositories (z. B. Git-Sync-Quellen) mit ihrer Quell-URL, Branch, Synchronisierungsstatus und Integrität auflistenprovisioning.repositories:readN/A
* Standardmäßig deaktiviert. Kategorie zu --enabled-tools hinzufügen, um sie zu aktivieren.

CLI-Flags-Referenz

Das Binary mcp-grafana unterstützt verschiedene Kommandozeilen-Flags zur Konfiguration:

Transportoptionen:

  • -t, --transport: Transporttyp (stdio, sse oder streamable-http) – Standard: stdio
  • --address: Host und Port für den SSE/streamable-http-Server – Standard: localhost:8000
  • --base-path: Basispfad für den SSE/streamable-http-Server
  • --endpoint-path: Endpunktpfad für den streamable-http-Server – Standard: /

HTTP-Transport-Sicherheit (nur SSE / streamable-http):

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

  • --allowed-hosts: Kommagetrennte Allowlist für Werte des Host-Headers. Standardmäßig Loopback-Varianten von --address (z. B. localhost:8000,127.0.0.1:8000,[::1]:8000). Ein Wert, der als leer geparst wird (nicht gesetzt, ,, , usw.), fällt ebenfalls auf die Standardwerte zurück, sodass ein Tippfehler die Prüfung nicht unbemerkt deaktivieren kann. Anfragen mit einem Host-Header außerhalb der Allowlist werden mit 403 abgelehnt. Übergeben Sie *, um die Prüfung zu deaktivieren – nur sicher, wenn Sie hinter einem vertrauenswürdigen Reverse-Proxy laufen, 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 einen tcpSocket-Probe / einen separaten Metrik-Port (--metrics-address).
  • --allowed-origins: Kommagetrennte Allowlist für Werte des Origin-Headers. Standardmäßig leer – jede Anfrage, die einen Origin-Header enthält, wird abgelehnt (Browser senden diesen immer bei Cross-Origin-Anfragen, und kein Browser sollte diesen Server direkt aufrufen). Setzen Sie eine explizite Liste, um browserbasierte Clients zuzulassen, oder *, um die Prüfung zu deaktivieren.

Debug und Logging:

  • --debug: Debug-Modus für detailliertes HTTP-Request/Response-Logging aktivieren
  • --log-level: Log-Level (debug, info, warn, error) – Standard: info

Observability:

  • --metrics: Prometheus-Metriken-Endpunkt 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 loggen, wenn eine MCP-Anfrage (Tool-Aufruf, Liste, Ressourcen-Lesevorgang usw.) länger als diese Dauer dauert. Akzeptiert Go-Duration-Strings (z. B. 500ms, 5s). Standard 0 deaktiviert das Logging langsamer Anfragen. Siehe Abschnitt Slow-request logging.
  • --slow-request-log-level: Log-Level für Slow-Request-Ereignisse (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 bereinigt – Standard: 30. Auf 0 setzen, um die Sitzungsbereinigung zu deaktivieren. Nur relevant für SSE- und streamable-http-Transporte.

Tool-Konfiguration:

  • --enabled-tools: Kommagetrennte Liste aktivierter Kategorien – Standard: alle Kategorien außer admin, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery und snowflake. Um deaktivierte Kategorien zu aktivieren, fügen Sie sie der 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 diesen Wert mindestens 1 unter Lokis serverseitigem max_entries_limit_per_query, um die Erkennung von Kürzungen zu ermöglichen (das Tool fordert intern limit+1 an, um zu erkennen, ob weitere Daten existieren).
  • --disable-search: Such-Tools deaktivieren
  • --disable-datasource: Datenquellen-Tools deaktivieren
  • --disable-incident: Incident-Tools deaktivieren
  • --disable-prometheus: Prometheus-Tools deaktivieren
  • --disable-write: Schreib-Tools deaktivieren (Erstellen/Aktualisieren)
  • --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-sift: Sift-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-examples: Query-Examples-Tools deaktivieren
  • --disable-clickhouse: ClickHouse-Tools deaktivieren
  • --disable-snowflake: Snowflake-Tools deaktivieren
  • --disable-runpanelquery: Run-Panel-Query-Tools deaktivieren
  • --disable-graphite: Graphite-Tools deaktivieren
  • --disable-athena: Athena-Tools deaktivieren
  • --disable-provisioning: Provisioning-Tools deaktivieren

Read-Only-Modus

Das Flag --disable-write bietet eine Möglichkeit, den MCP-Server im Read-Only-Modus auszuführen und jegliche Schreiboperationen auf 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 Service Accounts mit eingeschränkten Leseberechtigungen
  • Bereitstellung von Observability-Daten für KI-Assistenten ohne Änderungsmöglichkeiten
  • Betrieb in Produktionsumgebungen, in denen Schreibzugriff eingeschränkt werden soll
  • Test- und Entwicklungsszenarien, in denen versehentliche Änderungen verhindert werden sollen

Wenn --disable-write aktiviert ist, sind die folgenden Schreiboperationen deaktiviert:

Dashboard-Tools:

  • update_dashboard

Ordner-Tools:

  • create_folder

Incident-Tools:

  • create_incident
  • add_activity_to_incident

Alerting-Tools:

  • alerting_manage_rules (Erstellen, Aktualisieren, Löschen)

Annotation-Tools:

  • create_annotation
  • update_annotation

Sift-Tools:

  • find_error_pattern_logs (erstellt Investigations)
  • find_slow_requests (erstellt Investigations)

Snapshot-Tools:

  • create_snapshot
  • delete_snapshot

Alle Leseoperationen 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 privaten TLS-Schlüsseldatei für die Client-Authentifizierung
  • --tls-ca-file: Pfad zur TLS-CA-Zertifikatsdatei für die Server-Verifizierung
  • --tls-skip-verify: TLS-Zertifikatsverifizierung ü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 privaten TLS-Schlüsseldatei 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 Authentifizierung mit Service-Account-Token verwenden, erstellen Sie einen Service Account in Grafana mit ausreichenden Berechtigungen für die gewünschten Tools, generieren Sie ein Service-Account-Token und kopieren Sie es zur Verwendung in der Konfigurationsdatei in die Zwischenablage. Folgen Sie der Grafana Service-Account-Dokumentation für Details zur Erstellung von Service-Account-Tokens. Tipp: Wenn Sie sich mit der Konfiguration feingranularer RBAC-Bereiche nicht wohlfühlen, ist eine einfachere (aber weniger restriktive) Option, dem Service Account die integrierte Rolle Editor zuzuweisen. Dies gewährt breiten Lese-/Schreibzugriff, der die meisten MCP-Server-Operationen abdeckt – verwenden Sie dies, wenn Bequemlichkeit wichtiger ist als strikte Least-Privilege-Anforderungen.

    Hinweis: Die Umgebungsvariable GRAFANA_API_KEY ist veraltet und wird in einer zukünftigen Version entfernt. Bitte migrieren Sie stattdessen zu GRAFANA_SERVICE_ACCOUNT_TOKEN. Der alte Variablenname funktioniert aus Gründen der Abwärtskompatibilität weiterhin, zeigt jedoch Veraltungswarnungen an.

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

Dies ist besonders nützlich in Kubernetes, wo ein als Volume gemountetes Secret bei Änderung des zugrunde liegenden Secrets (typischerweise innerhalb von ~1 Minute) direkt aktualisiert wird. In Kombination mit dem pro Anfrage genutzten 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.

Multi-Organisations-Unterstützung

Sie können angeben, mit welcher Organisation interagiert werden soll, entweder über:

  • Umgebungsvariable: Setzen Sie GRAFANA_ORG_ID auf die numerische Organisations-ID
  • HTTP-Header: Setzen Sie X-Grafana-Org-Id bei Verwendung von SSE- oder streamable-HTTP-Transporten (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 bei allen Anfragen an Grafana, sodass Operationen im angegebenen Organisationskontext 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 allen Grafana-API-Anfragen beliebige HTTP-Header 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\"}"
      }
    }
  }
}

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

Wenn der MCP-Server hinter einem Gateway oder Reverse-Proxy läuft, der SSO handhabt (z. B. ein AWS ALB mit OIDC), muss das Session-Cookie jedes Benutzers Grafana erreichen, damit die Anfrage dem authentifizierten Benutzer zugeordnet werden kann. Die Umgebungsvariable GRAFANA_FORWARD_HEADERS ermöglicht dies, indem sie eine kommagetrennte Allowlist von Header-Namen angibt, die von 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). Im Stdio-Modus hat es keine Auswirkung.

Beispiel: Session-Cookie 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.

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

    • uvx (empfohlen): Wenn Sie uv installiert haben, ist kein zusätzliches Setup erforderlich – uvx lädt den Server automatisch herunter und führt ihn aus:

      uvx mcp-grafana

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

      Wichtig: Der Entrypoint des Docker-Images ist standardmäßig so konfiguriert, dass der MCP-Server 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 Standard 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
      1. SSE-Modus: In diesem Modus läuft der Server als HTTP-Server, zu 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> grafana/mcp-grafana

  2. Streamable-HTTP-Modus: In diesem Modus läuft der Server als eigenständiger Prozess, der mehrere Client-Verbindungen verarbeiten kann. Sie müssen Port 8000 mit dem Flag -p exponieren: Für diesen Modus müssen Sie den Standard 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> 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> \
  grafana/mcp-grafana \
  -t streamable-http \
  -addr :8443 \
  --server.tls-cert-file /certs/server.crt \
  --server.tls-key-file /certs/server.key

    • Binärdatei herunterladen: Laden Sie die neueste Version von mcp-grafana von der Releases-Seite herunter und legen Sie sie in Ihrem $PATH ab.

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

      GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

    • Bereitstellung in Kubernetes mit Helm: Verwenden Sie den 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

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

    Bei Verwendung von uvx:

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

    Bei Verwendung der Binärdatei:

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

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

Bei Verwendung von Docker:

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

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

Verwendung von VSCode mit einem entfernten MCP-Server

Wenn Sie VSCode verwenden und den MCP-Server im SSE-Modus betreiben (was der Standard ist, wenn Sie das Docker-Image ohne Überschreibung 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 liefert detaillierte Protokolle der 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:

Bei Verwendung der Binärdatei:

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

Bei Verwendung von Docker:

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

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

TLS-Konfiguration

Wenn Ihre Grafana-Instanz hinter mTLS läuft oder benutzerdefinierte TLS-Zertifikate erfordert, können Sie den MCP-Server für die Verwendung benutzerdefinierter Zertifikate konfigurieren. Der Server unterstützt die folgenden TLS-Konfigurationsoptionen:

  • --tls-cert-file: Pfad zur TLS-Zertifikatsdatei für die Client-Authentifizierung
  • --tls-key-file: Pfad zur privaten TLS-Schlüsseldatei für die Client-Authentifizierung
  • --tls-ca-file: Pfad zur TLS-CA-Zertifikatsdatei für die Server-Verifizierung
  • --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 vom MCP-Server verwendeten HTTP-Clients angewendet, einschließlich:

  • Dem Haupt-Grafana-OpenAPI-Client
  • Prometheus-Datenquellen-Clients
  • Loki-Datenquellen-Clients
  • Incident-Management-Clients
  • Sift-Untersuchungs-Clients
  • Alerting-Clients
  • Asserts-Clients

Beispiele für die direkte CLI-Nutzung:

Zum Testen mit selbstsignierten Zertifikaten:

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

Mit Client-Zertifikatsauthentifizierung:

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

Nur mit benutzerdefiniertem CA-Zertifikat:

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

Programmatische Nutzung:

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 beim Einbinden Ihres eigenen HTTP-Servers:

Wenn Bibliothekskonsumenten die Kontextfunktionen von mcp-grafana in ihren eigenen http.Server einbinden, installieren Sie ValidateGrafanaURLMiddleware, um fehlerhafte X-Grafana-URL-Header mit 400 Bad Request abzulehnen (entsprechend dem Verhalten der Binärdatei):

mux.Handle(path, mcpgrafana.ValidateGrafanaURLMiddleware(yourMCPHandler))

Wenn Sie NewGrafanaClient direkt aufrufen (Stdio oder programmatische Konstruktion), validieren Sie nicht vertrauenswürdige 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)

Beide Muster teilen sich ValidateGrafanaURL als einzigen Validator.

Server-TLS-Konfiguration (nur Streamable-HTTP-Transport)

Bei Verwendung des Streamable-HTTP-Transports (-t streamable-http) 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 (erforderlich für TLS)
  • --server.tls-key-file: Pfad zur privaten TLS-Schlüsseldatei für Server-HTTPS (erforderlich für TLS)

Hinweis: Diese Flags sind vollständig 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 der Streamable-HTTP-Transport verwendet wird.

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 sich dann mit https://localhost:8443/ anstelle von http://localhost:8000/ verbinden.

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 des SSE- (-t sse) oder Streamable-HTTP-Transports (-t streamable-http) 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

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

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.

Observability

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

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

Metriken

Bei Verwendung des SSE- oder Streamable-HTTP-Transports 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-Server-Anfragen (von otelhttp)

Hinweis: Metriken sind nur verfügbar, wenn SSE- oder Streamable-HTTP-Transporte verwendet werden. Sie sind nicht mit dem Stdio-Transport verfügbar.

Langsame-Anfragen-Protokollierung

Das Flag --slow-request-threshold gibt ein strukturiertes Log-Ereignis aus, sobald eine MCP-Anfrage (Tool-Aufruf, Liste, Ressourcen-Lesen 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 vorhanden bei tools/call-Methoden)
errorFehlerwert, wenn die Anfrage fehlgeschlagen ist (Best-Effort-Kontext; Inhalt wird durch Upstream-Fehlerverpackung gesteuert)
error.typeFehlerklassifizierung mit begrenzter Kardinalität (_OTHER für nicht typisierte Fehler)

Die Protokollierung langsamer Anfragen funktioniert mit allen Transporten (einschließlich Stdio) und erfordert kein --metrics. Der Standardschwellenwert von 0 deaktiviert sie vollständig. Proxied-Tools durchlaufen tools/call und werden automatisch abgedeckt.

Tracing

Verteiltes Tracing wird über die standardmäßigen Umgebungsvariablen OTEL_* konfiguriert und funktioniert unabhängig vom Flag --metrics. Wenn OTEL_EXPORTER_OTLP_ENDPOINT gesetzt ist, exportiert der Server Traces über OTLP/gRPC:

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

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

Tool-Aufruf-Spans folgen der Semconv-Benennung (tools/call <tool_name>) und enthalten Attribute wie gen_ai.tool.name, mcp.method.name und mcp.session.id. Der Server unterstützt auch die W3C-Trace-Context-Weitergabe aus dem Feld _meta von Tool-Aufruf-Anfragen.

Logs

Wenn OTEL_EXPORTER_OTLP_ENDPOINT (oder das signal-spezifische OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) gesetzt ist – derselbe Auslöser, der Tracing aktiviert – exportiert der Server zusätzlich zur bestehenden Klartext-Stderr-Ausgabe auch strukturierte Logs über OTLP/gRPC. Die Brücke otelslog hängt automatisch trace_id und span_id aus dem aktiven Span an, sodass Log-Einträge mit den Traces korrelieren, die der Server bereits ausgibt.

Die Stderr-Protokollierung bleibt unverändert, wenn OTLP-Logging aktiviert ist; Sie können sich weiterhin auf Container-Logs verlassen oder Stderr an /dev/null weiterleiten, wenn Sie dies 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 Sie OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (oder das generische OTEL_EXPORTER_OTLP_ENDPOINT) auf den entfernten gRPC-Endpunkt verweisen und die Authentifizierung über OTEL_EXPORTER_OTLP_LOGS_HEADERS (oder OTEL_EXPORTER_OTLP_HEADERS) bereitstellen, 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 Gegenstücke OTEL_EXPORTER_OTLP_* – 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 (Standardwarteschlange: 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 eine verlustfreie Pufferung bei Ausfällen benötigen.

Logs werden auch unter dem 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 datenquellenbezogenen Tools auf den folgenden Fehler stoßen:

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 API-Endpunkt /datasources/uid/{uid} wurde in Grafana 9.0 eingeführt, und Datenquellenoperationen schlagen in früheren Versionen fehl.

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

Entwicklung

Beiträge sind willkommen! 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 (was der Standard für die lokale Entwicklung ist), 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 dieses benutzerdefinierte Image standardmäßig den SSE-Modus als Einstiegspunkt. Um das Image zu bauen, 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 stehen drei Testarten zur Verfügung:

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

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

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

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

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

docker-compose up -d

Die Integrationstests können ausgeführt werden mit:

make test-all

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

Linting

Um den Code zu linten, führen Sie 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 ausführen mit:

make lint-jsonschema

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

Lizenz

Dieses Projekt ist lizenziert unter der Apache License, Version 2.0.