Grafana

officiel

Rechercher des tableaux de bord, enquêter sur des incidents et interroger des sources de données dans votre instance Grafana.

GitHub

3.5k

Essayer ce MCPSponsorisé

Que pouvez-vous faire avec Grafana MCP ?

Rechercher et inspecter les tableaux de bord — Demandez des tableaux de bord par titre, dossier, tag ou statut favori, puis extrayez des résumés, des versions ou des propriétés JSONPath spécifiques comme $.title via search_dashboards, get_dashboard_summary ou get_dashboard_property.
Interroger Prometheus et Loki — Exécutez des requêtes PromQL ou LogQL, récupérez les métadonnées de métriques/étiquettes et calculez les percentiles d'histogrammes (p50–p99) directement depuis vos sources de données.
Gérer les alertes et les incidents — Listez ou créez des règles d'alerte, vérifiez les statuts de déclenchement, et recherchez ou mettez à jour les enregistrements d'incidents Grafana avec des champs personnalisés.
Explorer les données SQL et CloudWatch — Listez les tables, décrivez les schémas et exécutez du SQL avec des macros sur ClickHouse, Snowflake, Athena, MySQL, PostgreSQL ou MSSQL ; interrogez également les métriques CloudWatch par espace de noms et dimension.
Rendre les tableaux de bord et générer des liens — Obtenez un panneau ou un tableau de bord en image PNG, ou créez des liens profonds précis vers les tableaux de bord, les panneaux et Explore avec des plages horaires et des variables.

Documentation

Serveur MCP Grafana

Un serveur Model Context Protocol (MCP) pour Grafana.

Celui-ci fournit un accès à votre instance Grafana et à son écosystème environnant.

Démarrage rapide

Nécessite uv. Ajoutez ce qui suit à votre configuration client MCP (par exemple Claude Desktop, Cursor) :

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

Pour Grafana Cloud, remplacez GRAFANA_URL par l'URL de votre instance (par exemple https://myinstance.grafana.net). Consultez Utilisation pour plus d'options d'installation, notamment Docker, binaire et Helm.

Prérequis

Grafana version 9.0 ou ultérieure est requis pour une fonctionnalité complète. Certaines fonctionnalités, en particulier les opérations liées aux sources de données, peuvent ne pas fonctionner correctement avec des versions antérieures en raison de points de terminaison d'API manquants.

Fonctionnalités

Les fonctionnalités suivantes sont actuellement disponibles dans le serveur MCP. Cette liste est fournie à titre informatif uniquement et ne représente pas une feuille de route ni un engagement envers des fonctionnalités futures.

Tableaux de bord

Rechercher des tableaux de bord : Trouvez des tableaux de bord par titre, UID de dossier, tag ou statut favori
Obtenir un tableau de bord par UID : Récupérez les détails complets d'un tableau de bord à l'aide de son identifiant unique. Passez l'option version pour charger un instantané enregistré au lieu du tableau de bord actuel. Avertissement : Les grands tableaux de bord peuvent consommer un espace de contexte important.
Lister les versions d'un tableau de bord : Listez les versions enregistrées d'un tableau de bord sous forme de métadonnées compactes (numéro de version, auteur, horodatage, message d'enregistrement)
Obtenir un résumé du tableau de bord : Obtenez un aperçu compact d'un tableau de bord, y compris le titre, le nombre de panneaux, les types de panneaux, les variables et les métadonnées, sans le JSON complet afin de minimiser l'utilisation de l'espace de contexte
Obtenir une propriété du tableau de bord : Extrayez des parties spécifiques d'un tableau de bord à l'aide d'expressions JSONPath (par exemple $.title, $.panels[*].title) pour ne récupérer que les données nécessaires et réduire la consommation d'espace de contexte
Mettre à jour ou créer un tableau de bord : Modifiez des tableaux de bord existants ou créez-en de nouveaux. Avertissement : Nécessite le JSON complet du tableau de bord, ce qui peut consommer de grandes quantités d'espace de contexte.
Corriger un tableau de bord : Appliquez des modifications spécifiques à un tableau de bord sans nécessiter le JSON complet, réduisant considérablement l'utilisation de l'espace de contexte pour des modifications ciblées
Obtenir les requêtes de panneau et les informations de source de données : Obtenez le titre, la chaîne de requête et les informations de source de données (y compris l'UID et le type, si disponibles) de chaque panneau d'un tableau de bord

Exécuter une requête de panneau

Remarque : Les outils d'exécution de requête de panneau sont désactivés par défaut. Pour les activer, ajoutez runpanelquery à votre indicateur --enabled-tools.

Exécuter une requête de panneau : Exécutez la requête d'un panneau de tableau de bord avec des plages de temps personnalisées et des remplacements de variables.

Gestion de l'espace de contexte

Les outils de tableau de bord incluent désormais plusieurs stratégies pour gérer efficacement l'utilisation de l'espace de contexte (problème #101) :

Utilisez get_dashboard_summary pour la vue d'ensemble du tableau de bord et la planification des modifications
Utilisez get_dashboard_property avec JSONPath lorsque vous n'avez besoin que de parties spécifiques du tableau de bord
Évitez get_dashboard_by_uid sauf si vous avez spécifiquement besoin du JSON complet du tableau de bord

Sources de données

Lister et récupérer les informations des sources de données : Affichez toutes les sources de données configurées et récupérez des informations détaillées sur chacune.
- Types de sources de données pris en charge : Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Exemples de requêtes

Remarque : Les outils d'exemples de requêtes sont désactivés par défaut. Pour les activer, ajoutez examples à votre indicateur --enabled-tools.

Obtenir des exemples de requêtes : Récupérez des exemples de requêtes pour différents types de sources de données afin d'apprendre la syntaxe des requêtes.

Interrogation Prometheus

Interroger Prometheus : Exécutez des requêtes PromQL (prend en charge les requêtes métriques instantanées et sur plage) contre les sources de données Prometheus.
Interroger les métadonnées Prometheus : Récupérez les métadonnées de métriques, les noms de métriques, les noms d'étiquettes et les valeurs d'étiquettes depuis les sources de données Prometheus.
Interroger les percentiles d'histogrammes : Calculez les valeurs de percentiles d'histogrammes (p50, p90, p95, p99) à l'aide de histogram_quantile.

Interrogation Loki

Interroger les journaux et métriques Loki : Exécutez des requêtes de journaux et des requêtes métriques à l'aide de LogQL contre les sources de données Loki.
Interroger les métadonnées Loki : Récupérez les noms d'étiquettes, les valeurs d'étiquettes et les statistiques de flux depuis les sources de données Loki.
Interroger les modèles Loki : Récupérez les modèles de journaux détectés par Loki pour identifier les structures de journaux courantes et les anomalies.

Interrogation InfluxDB

Remarque : Les outils InfluxDB sont désactivés par défaut. Pour les activer, ajoutez influxdb à votre indicateur --enabled-tools.

Interroger InfluxDB : Exécutez des requêtes contre les sources de données InfluxDB en utilisant InfluxQL (v1.x) ou Flux (v2.x). Le dialecte est déduit de la configuration de la source de données, ou peut être défini explicitement via le paramètre dialect.

Interrogation des sources de données SQL

Remarque : Les outils SQL sont désactivés par défaut. Pour les activer, ajoutez sql à votre indicateur --enabled-tools. Les alias de rétrocompatibilité clickhouse, snowflake et athena fonctionnent également.

Les outils SQL unifiés prennent en charge ClickHouse, Snowflake, Athena, MySQL, PostgreSQL et MSSQL via un ensemble unique d'outils. Les requêtes passent par les plugins de sources de données de Grafana, donc l'authentification est gérée par la configuration de la source de données — les identifiants ne sont jamais vus par le serveur MCP.

Lister les bases de données/schémas/catalogues : Découvrez les unités organisationnelles d'une source de données SQL. Pour Athena, omettez le catalogue pour lister les catalogues, ou passez un catalogue pour lister les bases de données.
Lister les tables : Listez les tables dans une base de données ou un schéma avec des métadonnées (nombre de lignes, tailles lorsque disponibles).
Décrire le schéma d'une table : Obtenez les noms de colonnes, les types, la nullabilité, les valeurs par défaut et les commentaires.
Interroger SQL : Exécutez des requêtes SQL avec substitution de macros spécifiques à la source de données ($__timeFilter(col), $__from/$__to, $__interval, ${varname}), application automatique de limites et prise en charge des variables de modèle.

Interrogation CloudWatch

Remarque : Les outils CloudWatch sont désactivés par défaut. Pour les activer, ajoutez cloudwatch à votre indicateur --enabled-tools.

Lister les espaces de noms CloudWatch : Découvrez les espaces de noms AWS CloudWatch disponibles.
Lister les métriques CloudWatch : Listez les métriques disponibles dans un espace de noms spécifique.
Lister les dimensions CloudWatch : Obtenez les dimensions pour filtrer les requêtes métriques.
Interroger CloudWatch : Exécutez des requêtes métriques CloudWatch avec prise en charge des plages de temps.

Interrogation Google Cloud Logging

Remarque : Les outils Google Cloud Logging sont désactivés par défaut. Pour les activer, ajoutez cloudlogging à votre indicateur --enabled-tools. Nécessite le plugin de source de données Google Cloud Logging (googlecloud-logging-datasource) version 1.8.0 ou ultérieure, qui nécessite Grafana 11.2+. Les versions antérieures du plugin renvoient une disposition de réponse différente et query_cloud_logging signale une erreur demandant une mise à niveau.

Lister les projets Cloud Logging : Découvrez les ID de projets GCP à partir desquels la source de données peut lire les journaux.
Lister les buckets et vues Cloud Logging : Découvrez les buckets de journaux et les vues de journaux pour délimiter une requête.
Interroger Cloud Logging : Exécutez des filtres de langage de requête Cloud Logging (par exemple resource.type="k8s_container" AND severity>=ERROR) avec plage de temps et limite ; renvoie les entrées du plus récent au plus ancien avec sévérité, corps, étiquettes et ID de trace. L'authentification GCP est gérée par la configuration de la source de données.

Interrogation Graphite

Remarque : Les outils Graphite sont désactivés par défaut. Pour les activer, ajoutez graphite à votre indicateur --enabled-tools.

Interroger Graphite : Exécutez des requêtes de l'API de rendu Graphite contre une source de données Graphite.
Lister les métriques Graphite : Parcourez et découvrez les chemins de métriques Graphite.
Lister les tags Graphite : Listez les tags Graphite disponibles et leurs valeurs.
Interroger la densité Graphite : Interrogez la densité des métriques Graphite pour un modèle donné.

Interrogation Elasticsearch/OpenSearch

Remarque : Les outils Elasticsearch/OpenSearch sont désactivés par défaut. Pour les activer, ajoutez elasticsearch à votre indicateur --enabled-tools.

Interroger Elasticsearch/OpenSearch : Exécutez des requêtes de recherche contre les sources de données Elasticsearch ou OpenSearch en utilisant la syntaxe de requête Lucene ou le DSL de requête Elasticsearch. Prend en charge le filtrage par plage de temps et la récupération de journaux, métriques ou toute donnée indexée. Renvoie les documents avec leur index, ID, champs source et score de pertinence optionnel.

Interrogation Quickwit

Remarque : Les outils Quickwit sont désactivés par défaut. Pour les activer, ajoutez quickwit à votre indicateur --enabled-tools.

Interroger Quickwit : Exécutez des requêtes de recherche contre les sources de données Quickwit en utilisant la syntaxe de requête Lucene ou un DSL de requête partiellement compatible Elasticsearch. Prend en charge le filtrage par plage de temps et la récupération de journaux ou d'autres documents indexés. Renvoie les documents avec leur index, ID, champs source et score de pertinence optionnel.

Observabilité des agents

Remarque : Les outils d'observabilité des agents sont désactivés par défaut et fonctionnent uniquement dans Grafana Cloud. Pour les activer, ajoutez agento11y à votre indicateur --enabled-tools.

Lister et rechercher des conversations : Listez les conversations LLM récentes ou recherchez-les avec une expression de filtre (modèle, fournisseur, agent, statut, type d'erreur, résultats d'évaluation, etc.) sur une plage de temps. Les résultats de recherche incluent les compteurs d'erreurs, les résumés de notes, les résumés d'évaluation et les identifiants de trace.
Obtenir le détail d'une conversation : Récupérez une seule conversation avec toutes ses générations, y compris les invites et les sorties.
Obtenir le détail et les scores d'une génération : Récupérez une seule génération par son identifiant, ainsi que ses scores d'évaluation (évaluateur, clé de score, valeur, réussite, explication).
Lire le catalogue d'agents : Listez les agents qui envoient de la télémétrie, récupérez une version d'agent en entier (invite système complète, chaque outil avec son schéma JSON, et les modèles sur lesquels il a tourné), parcourez l'historique des versions d'un agent, et comparez les agrégats de scores d'évaluation par version. Les versions effectives sont des hachages sha256: qu'un changement d'outil n'affecte jamais ; pour un agent qui ne signale pas sa propre version, ils hachent l'invite système, donc une modification d'invite crée une nouvelle version. Les lignes du catalogue et des versions portent un token_estimate, qu'il vaut la peine de vérifier avant de récupérer une invite complète.
Inspecter les évaluateurs et les modèles : Lisez les évaluateurs dont provient un score, les modèles dont ils sont dérivés, et les fournisseurs et modèles de juges disponibles pour les évaluateurs à juge LLM. Avec les outils d'écriture activés, créez, dupliquez, testez et supprimez également des évaluateurs.
Inspecter les règles d'évaluation et les garde-fous : Lisez les règles d'évaluation asynchrones qui lient les évaluateurs au trafic de production, et les garde-fous (règles de hook) qui s'exécutent en ligne et peuvent avertir ou refuser. Avec les outils d'écriture activés, créez, mettez à jour, prévisualisez et supprimez-les également. Les écritures et les opérations non persistantes preview_rule et test_evaluator nécessitent la permission grafana-agento11y-app.eval:write, accordée par le rôle Admin Agento11y.
Organiser les conversations et collections enregistrées : Lisez les conversations enregistrées (signets qui donnent à une conversation un identifiant, un nom et des balises stables) et les collections qui les regroupent, y compris le nombre de membres de chaque collection et les collections intégrées dans chaque ligne de conversation enregistrée. Avec les outils d'écriture activés, marquez également une conversation, créez et modifiez des collections, et ajoutez ou supprimez des membres. Ces écritures nécessitent la même permission grafana-agento11y-app.eval:write.
Lire et modifier les suites de tests : Listez les suites de tests versionnées sur lesquelles les expériences hors ligne s'exécutent, lisez-en une avec son historique complet de versions, et parcourez les cas de test d'une version. Avec les outils d'écriture activés, créez également une suite, renommez-la ou rebalisez-la, ouvrez une version brouillon, publiez-la, et écrivez ou supprimez ses cas de test. Une version publiée est figée, donc une modification signifie ouvrir un nouveau brouillon. Ces écritures nécessitent grafana-agento11y-app.eval:write.
Lire les expériences hors ligne : Listez les exécutions d'évaluation sur une suite de tests et lisez-en une avec son taux de réussite principal, son coût et ses totaux de jetons. Descendez à travers un rapport par cas de test jusqu'aux essais, leurs scores avec l'explication de chaque juge, et leurs métadonnées d'artefact. Avec les outils d'écriture activés, renommez ou rebalisez également une expérience et annulez une expérience en cours, ce qui nécessite grafana-agento11y-app.eval:write. Les expériences sont créées par les exécuteurs SDK, pas par cet outil.

Assistant Grafana

Remarque : Les outils de l'assistant sont désactivés par défaut et nécessitent le plugin Assistant Grafana (grafana-assistant-app) installé sur l'instance Grafana cible. Ce sont également des outils d'écriture (l'assistant peut modifier l'état de la pile), donc ils sont ignorés lorsque --disable-write est défini. Pour les activer, ajoutez assistant à votre indicateur --enabled-tools.

Interroger l'assistant : Envoyez une invite en langage naturel à l'Assistant Grafana et attendez la réponse texte complète. L'assistant peut utiliser des outils, des métriques, des journaux et d'autres contextes de la pile—plus large que de déclencher une seule requête de source de données isolée. Passez le contextId retourné dans un appel de suivi pour continuer la même conversation. Les tâches complexes peuvent prendre plusieurs minutes ; l'appel bloque jusqu'à ce que la réponse soit terminée ou que la requête expire (5 minutes).

Incidents

Rechercher, créer et mettre à jour des incidents : Gérez les incidents dans Grafana Incident, y compris la recherche, la création, l'ajout d'activités, et la lecture ou la définition de champs personnalisés.

Enquêtes Sift

Lister les enquêtes Sift : Récupérez une liste d'enquêtes Sift, avec prise en charge d'un paramètre de limite.
Obtenir une enquête Sift : Récupérez les détails d'une enquête Sift spécifique par son UUID.
Obtenir les analyses Sift : Récupérez une analyse spécifique d'une enquête Sift.
Trouver des modèles d'erreur dans les journaux : Détectez des modèles d'erreur élevés dans les journaux Loki à l'aide de Sift.
Trouver des requêtes lentes : Détectez des requêtes lentes à l'aide de Sift (Tempo).

Alerting

Lister et récupérer les informations des règles d'alerte : Affichez les règles d'alerte et leurs statuts (déclenchée/normale/erreur/etc.) dans Grafana. Prend en charge les règles gérées par Grafana et les règles gérées par les sources de données Prometheus ou Loki.
Créer et mettre à jour des règles d'alerte : Créez de nouvelles règles d'alerte ou modifiez celles existantes.
Supprimer des règles d'alerte : Supprimez les règles d'alerte par UID.
Gérer le routage des alertes : Affichez les politiques de notification, les points de contact et les intervalles de temps. Prend en charge les points de contact gérés par Grafana et les récepteurs de sources de données Alertmanager externes (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

Lister et gérer les plannings : Affichez et gérez les plannings d'astreinte dans Grafana OnCall.
Obtenir les détails des quarts : Récupérez des informations détaillées sur des quarts d'astreinte spécifiques.
Obtenir les utilisateurs d'astreinte actuels : Voyez quels utilisateurs sont actuellement d'astreinte pour un planning.
Lister les équipes et les utilisateurs : Affichez toutes les équipes et tous les utilisateurs OnCall.
Lister les groupes d'alertes : Affichez et filtrez les groupes d'alertes de Grafana OnCall par divers critères, y compris l'état, l'intégration, les étiquettes et la plage de temps.
Obtenir les détails d'un groupe d'alertes : Récupérez des informations détaillées sur un groupe d'alertes spécifique par son identifiant.

Administration

Remarque : Les outils d'administration sont désactivés par défaut. Pour les activer, incluez admin dans votre indicateur --enabled-tools.

Lister les équipes : Affichez toutes les équipes configurées dans Grafana.
Lister les utilisateurs : Affichez tous les utilisateurs d'une organisation dans Grafana.
Lister tous les rôles : Listez tous les rôles Grafana, avec un filtre optionnel pour les rôles déléguables.
Obtenir les détails d'un rôle : Obtenez les détails d'un rôle Grafana spécifique par UID.
Lister les affectations pour un rôle : Listez tous les utilisateurs, équipes et comptes de service affectés à un rôle.
Lister les rôles pour les utilisateurs : Listez tous les rôles affectés à un ou plusieurs utilisateurs.
Lister les rôles pour les équipes : Listez tous les rôles affectés à une ou plusieurs équipes.
Lister les permissions pour une ressource : Listez toutes les permissions définies pour une ressource spécifique (tableau de bord, source de données, dossier, etc.).
Décrire une ressource Grafana : Listez les permissions disponibles et les capacités d'affectation pour un type de ressource.

Utilisateur

Informations utilisateur : Obtenez l'identité Grafana actuelle — identifiant, e-mail, nom, s'il s'agit d'un administrateur Grafana (serveur), l'organisation actuelle et les organisations auxquelles l'identifiant peut accéder (avec les rôles). Utilisez-le pour découvrir les valeurs valides de orgId pour les requêtes multi-organisation.

Navigation

Générer des liens profonds : Créez des URL de liens profonds précises pour les ressources Grafana au lieu de vous fier aux suppositions d'URL du LLM.
- Liens de tableaux de bord : Générez des liens directs vers les tableaux de bord en utilisant leur UID (par exemple, http://localhost:3000/d/dashboard-uid)
- Liens de panneaux : Créez des liens vers des panneaux spécifiques dans les tableaux de bord avec le paramètre viewPanel (par exemple, http://localhost:3000/d/dashboard-uid?viewPanel=5)
- Liens Explorer : Générez des liens vers Grafana Explorer avec des sources de données préconfigurées (par exemple, http://localhost:3000/explore?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}). Grafana antérieur à 10.2 ne comprend pas panes, donc le format hérité ?left={...} est émis pour ces versions à la place.
- Prise en charge de la plage de temps : Ajoutez des paramètres de plage de temps aux liens (from=now-1h&to=now)
- Paramètres personnalisés : Incluez des paramètres de requête supplémentaires comme les variables de tableau de bord ou les intervalles de rafraîchissement

Annotations

Obtenir des annotations : Interrogez les annotations avec des filtres. Prend en charge la plage de temps, l'UID du tableau de bord, les balises et le mode de correspondance.
Créer une annotation : Créez une nouvelle annotation sur un tableau de bord ou un panneau.
Créer une annotation Graphite : Créez des annotations au format Graphite (what, when, tags, data).
Mettre à jour une annotation : Remplacez tous les champs d'une annotation existante (mise à jour complète).
Corriger une annotation : Mettez à jour uniquement des champs spécifiques d'une annotation (mise à jour partielle).
Supprimer une annotation : Supprimez définitivement une annotation par identifiant.
Obtenir les balises d'annotation : Listez les balises d'annotation disponibles avec un filtrage optionnel.

Instantanés

Lister les instantanés : Listez les instantanés de tableaux de bord avec des filtres de requête et de limite optionnels.
Obtenir un instantané : Récupérez les métadonnées de l'instantané et la charge utile du tableau de bord par clé d'instantané.
Créer un instantané : Créez un instantané de tableau de bord à partir d'une charge utile complète de tableau de bord, avec une expiration optionnelle et des options d'instantané externe.
Supprimer un instantané : Supprimez un instantané par clé d'instantané.

Rendu

Obtenir une image de panneau ou de tableau de bord : Rendez un panneau de tableau de bord Grafana ou un tableau de bord complet en image PNG. Renvoie l'image sous forme de données encodées en base64 pour une utilisation dans des rapports, des alertes ou des présentations. Prend en charge la personnalisation des dimensions, de la plage de temps, du thème, de l'échelle et des variables de tableau de bord. Prend également en charge le rendu de tableaux de bord non encore appliqués à partir d'une branche de référentiel de provisionnement (par exemple, un aperçu de PR git-sync) via le paramètre optionnel provisioningPreview.
- Remarque : Nécessite le service Grafana Image Renderer installé et configuré.

Provisionnement

Lister les référentiels de provisionnement : Listez les référentiels de provisionnement configurés pour cette instance Grafana (par exemple, les sources git-sync), en renvoyant le slug de chaque référentiel avec son URL source, sa branche, son chemin, son état de synchronisation et sa santé.
Valider un fichier de provisionnement : Appliquez à sec un fichier d'un référentiel de provisionnement à une branche ou un commit donné. Renvoie s'il serait accepté, l'action de ressource (créer/mettre à jour), le type de ressource cible et toute erreur de validation structurée—la même surface d'admission que le commentateur de PR de Grafana utilise.

La liste des outils est configurable, vous pouvez donc choisir les outils que vous souhaitez mettre à disposition du client MCP. C'est utile si vous n'utilisez pas certaines fonctionnalités ou si vous ne voulez pas occuper trop de la fenêtre de contexte. Pour désactiver une catégorie d'outils, utilisez l'indicateur --disable-<category> au démarrage du serveur. Par exemple, pour désactiver les outils OnCall, utilisez --disable-oncall, ou pour désactiver la génération de liens profonds de navigation, utilisez --disable-navigation.

Permissions RBAC

Chaque outil nécessite des permissions RBAC spécifiques pour fonctionner correctement. Lors de la création d'un compte de service pour le serveur MCP, assurez-vous qu'il dispose des permissions nécessaires en fonction des outils que vous prévoyez d'utiliser. Les permissions listées sont les actions minimales requises—vous pouvez également avoir besoin de portées appropriées (par exemple, datasources:*, dashboards:*, folders:*) selon votre cas d'utilisation.

Astuce : Si vous n'êtes pas familier avec le RBAC Grafana ou si vous souhaitez une configuration plus rapide et plus simple au lieu de configurer de nombreuses portées granulaires, vous pouvez attribuer un rôle intégré tel que Editor au compte de service. Le rôle Editor accorde un accès large en lecture/écriture qui permettra la plupart des opérations du serveur MCP ; il est moins granulaire (et donc moins restrictif) que les portées appliquées manuellement, utilisez-le donc uniquement lorsque la commodité est plus importante qu'un accès strict au moindre privilège.

Remarque : Les outils Grafana Incident et Sift utilisent les rôles Grafana de base au lieu des permissions RBAC fines :

Rôle Viewer : Requis pour les opérations en lecture seule (lister les incidents, obtenir les enquêtes)
Rôle Editor : Requis pour les opérations d'écriture (créer des incidents, modifier des enquêtes)

Pour plus d'informations sur le RBAC Grafana, consultez la documentation officielle.

Portées RBAC

Les portées définissent les ressources spécifiques auxquelles les permissions s'appliquent. Chaque action nécessite à la fois la permission et la combinaison de portée appropriées.

Modèles de portée courants :

Accès large : Utilisez les caractères génériques * pour un accès à l’échelle de l’organisation
- datasources:* - Accès à toutes les sources de données
- dashboards:* - Accès à tous les tableaux de bord
- folders:* - Accès à tous les dossiers
- teams:* - Accès à toutes les équipes
Accès limité : Utilisez des UID ou des ID spécifiques pour restreindre l’accès à des ressources individuelles
- datasources:uid:prometheus-uid - Accès uniquement à une source de données Prometheus spécifique
- dashboards:uid:abc123 - Accès uniquement au tableau de bord avec l’UID abc123
- folders:uid:xyz789 - Accès uniquement au dossier avec l’UID xyz789
- teams:id:5 - Accès uniquement à l’équipe avec l’ID 5
- global.users:id:123 - Accès uniquement à l’utilisateur avec l’ID 123

Exemples :

Accès complet au serveur MCP : Accordez des autorisations étendues pour tous les outils

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)

Accès limité aux sources de données : Interrogez uniquement des instances Prometheus et Loki spécifiques
```
datasources:uid:prometheus-prod (datasources:query)
datasources:uid:loki-prod (datasources:query)
```

Accès spécifique aux tableaux de bord : Lisez uniquement des tableaux de bord spécifiques

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

Outils

Outil	Catégorie	Description	Autorisations RBAC requises	Scopes requis
`list_teams`	Admin	Lister toutes les équipes	`teams:read`	`teams:*` ou `teams:id:1`
`list_users_by_org`	Admin	Lister tous les utilisateurs d'une organisation	`users:read`	`global.users:*` ou `global.users:id:123`
`list_all_roles`	Admin	Lister tous les rôles Grafana	`roles:read`	`roles:*`
`get_role_details`	Admin	Obtenir les détails d'un rôle Grafana	`roles:read`	`roles:uid:editor`
`get_role_assignments`	Admin	Lister les affectations pour un rôle	`roles:read`	`roles:uid:editor`
`list_user_roles`	Admin	Lister les rôles pour les utilisateurs	`roles:read`	`global.users:id:123`
`list_team_roles`	Admin	Lister les rôles pour les équipes	`roles:read`	`teams:id:7`
`get_resource_permissions`	Admin	Lister les autorisations pour une ressource	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	Admin	Décrire un type de ressource Grafana	`permissions:read`	`dashboards:*`
`user_info`	Utilisateur	Identité actuelle, capacités et organisations accessibles	Aucune (utilisateur connecté)	—
`search_dashboards`	Recherche	Rechercher des tableaux de bord par requête, UID de dossier, étiquette ou favori	`dashboards:read`	`dashboards:*` ou `dashboards:uid:abc123`
`get_dashboard_by_uid`	Tableau de bord	Obtenir un tableau de bord par uid, éventuellement une version enregistrée	`dashboards:read`	`dashboards:uid:abc123`
`list_dashboard_versions`	Tableau de bord	Lister les versions enregistrées d'un tableau de bord (version, auteur, heure, message)	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	Tableau de bord	Mettre à jour ou créer un nouveau tableau de bord	`dashboards:create`, `dashboards:write`	`dashboards:`, `folders:` ou `folders:uid:xyz789`
`get_dashboard_panel_queries`	Tableau de bord	Obtenir le titre du panneau, les requêtes, l'UID et le type de source de données d'un tableau de bord	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	ExécuterRequêtePanneau*	Exécuter une ou plusieurs requêtes de panneau de tableau de bord	`dashboards:read`, `datasources:query`	`dashboards:uid:`, `datasources:uid:`
`get_dashboard_property`	Tableau de bord	Extraire des parties spécifiques d'un tableau de bord à l'aide d'expressions JSONPath	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	Tableau de bord	Obtenir un résumé compact d'un tableau de bord sans le JSON complet	`dashboards:read`	`dashboards:uid:abc123`
`list_datasources`	Sources de données	Lister les sources de données	`datasources:read`	`datasources:*`
`get_datasource`	Sources de données	Obtenir une source de données par UID ou nom	`datasources:read`	`datasources:uid:prometheus-uid`
`get_query_examples`	Exemples*	Obtenir des exemples de requêtes pour un type de source de données	`datasources:read`	`datasources:*`
`query_prometheus`	Prometheus	Exécuter une requête contre une source de données Prometheus	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_metadata`	Prometheus	Lister les métadonnées des métriques	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	Lister les noms de métriques disponibles	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	Lister les noms d'étiquettes correspondant à un sélecteur	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	Lister les valeurs pour une étiquette spécifique	`datasources:query`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	Calculer les valeurs de percentile d'histogramme	`datasources:query`	`datasources:uid:prometheus-uid`
`list_incidents`	Incident	Lister les incidents dans Grafana Incident, éventuellement avec leurs valeurs de champs personnalisés	Rôle Viewer	N/A
`create_incident`	Incident	Créer un incident dans Grafana Incident, en définissant éventuellement des champs personnalisés	Rôle Editor	N/A
`add_activity_to_incident`	Incident	Ajouter un élément d'activité à un incident dans Grafana Incident	Rôle Editor	N/A
`update_incident`	Incident	Mettre à jour un incident dans Grafana Incident (statut, gravité, titre ou champs personnalisés)	Rôle Editor	N/A
`get_incident`	Incident	Obtenir un incident unique par ID, y compris ses champs personnalisés	Rôle Viewer	N/A
`list_incident_custom_fields`	Incident	Lister les champs personnalisés configurés pour les incidents, avec leurs types et options de sélection	Rôle Viewer	N/A
`query_loki_logs`	Loki	Interroger et récupérer des journaux à l'aide de LogQL (requêtes de journaux ou de métriques)	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	Lister tous les noms d'étiquettes disponibles dans les journaux	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	Lister les valeurs pour une étiquette de journal spécifique	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	Obtenir des statistiques sur les flux de journaux	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	Interroger les modèles de journaux détectés pour identifier les structures courantes	`datasources:query`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	Auditer une stratégie d'étiquettes Loki (live ou statique) et diagnostiquer éventuellement les performances des requêtes	`datasources:query`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Configuration	Générer un extrait Alloy `loki.process` appliquant les étiquettes approuvées	N/A	N/A
`query_influxdb`	InfluxDB	Interroger InfluxDB en utilisant InfluxQL (v1) ou Flux (v2)	`datasources:query`	`datasources:uid:influxdb-uid`
`list_sql_databases`	SQL*	Lister les bases de données, schémas ou catalogues d'une source de données SQL	`datasources:query`	`datasources:uid:*`
`list_sql_tables`	SQL*	Lister les tables d'une source de données SQL	`datasources:query`	`datasources:uid:*`
`describe_sql_table`	SQL*	Obtenir le schéma des colonnes d'une table	`datasources:query`	`datasources:uid:*`
`query_sql`	SQL*	Exécuter des requêtes SQL avec substitution de macros	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	Lister les espaces de noms AWS CloudWatch disponibles	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	Lister les métriques dans un espace de noms	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	Lister les dimensions d'une métrique	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimension_values`	CloudWatch*	Lister les valeurs pour une clé de dimension	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	Exécuter des requêtes de métriques CloudWatch	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_projects`	Cloud Logging*	Lister les projets GCP lisibles par une source de données Google Cloud Logging	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_buckets`	Cloud Logging*	Lister les buckets de journaux dans un projet GCP	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_views`	Cloud Logging*	Lister les vues de journaux dans un bucket de journaux	`datasources:query`	`datasources:uid:*`
`query_cloud_logging`	Cloud Logging*	Interroger les journaux avec le langage de requête Cloud Logging	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	Interroger Elasticsearch ou OpenSearch en utilisant la syntaxe Lucene ou Query DSL	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	Interroger Quickwit en utilisant la syntaxe Lucene ou Query DSL	`datasources:query`	`datasources:uid:quickwit-uid`
`alerting_manage_rules`	Alerting	Gérer les règles d'alerte (lister, obtenir, versions, créer, mettre à jour, supprimer)	`alert.rules:read` + `alert.rules:write` pour les mutations	`folders:*` ou `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	Gérer les politiques de notification, les points de contact et les intervalles de temps	`alert.notifications:read`	Portée globale
`alerting_manage_silences`	Alerting	Gérer les silences d'alerting (lister, obtenir, créer, mettre à jour, expirer)	`alert.instances:read` + `alert.instances:write` pour les mutations	Portée globale
`list_oncall_schedules`	OnCall	Lister les plannings de Grafana OnCall	`grafana-oncall-app.schedules:read`	Portées spécifiques aux plugins
`get_oncall_shift`	OnCall	Obtenir les détails d'un quart de travail OnCall spécifique	`grafana-oncall-app.schedules:read`	Portées spécifiques aux plugins
`get_current_oncall_users`	OnCall	Obtenir les utilisateurs actuellement de garde pour un planning spécifique	`grafana-oncall-app.schedules:read`	Portées spécifiques aux plugins
`list_oncall_teams`	OnCall	Lister les équipes de Grafana OnCall	`grafana-oncall-app.user-settings:read`	Portées spécifiques aux plugins
`list_oncall_users`	OnCall	Lister les utilisateurs de Grafana OnCall	`grafana-oncall-app.user-settings:read`	Portées spécifiques aux plugins
`list_alert_groups`	OnCall	Lister les groupes d'alertes de Grafana OnCall avec des options de filtrage	`grafana-oncall-app.alert-groups:read`	Portées spécifiques aux plugins
`get_alert_group`	OnCall	Obtenir un groupe d'alertes spécifique de Grafana OnCall par son ID	`grafana-oncall-app.alert-groups:read`	Portées spécifiques aux plugins
`update_alert_group`	OnCall	Accuser réception, annuler l'accusé de réception, résoudre ou annuler la résolution d'un groupe d'alertes	`grafana-oncall-app.alert-groups:write` (et `:read`)	Portées spécifiques aux plugins
`get_sift_investigation`	Sift	Récupérer une enquête Sift existante par son UUID	Rôle de visualisation	N/A
`get_sift_analysis`	Sift	Récupérer une analyse spécifique d'une enquête Sift	Rôle de visualisation	N/A
`list_sift_investigations`	Sift	Récupérer une liste d'enquêtes Sift avec une limite facultative	Rôle de visualisation	N/A
`find_error_pattern_logs`	Sift	Détecte les modèles d'erreurs élevés dans les journaux Loki.	Rôle d'éditeur	N/A
`find_slow_requests`	Sift	Détecte les requêtes lentes à partir des sources de données tempo pertinentes.	Rôle d'éditeur	N/A
`list_pyroscope_label_names`	Pyroscope	Lister les noms d'étiquettes correspondant à un sélecteur	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	Lister les valeurs d'étiquettes correspondant à un sélecteur pour un nom d'étiquette	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	Lister les types de profils disponibles	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	Interroger les profils, les métriques, ou les deux à partir de Pyroscope	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	Obtenir le résumé des assertions pour une entité donnée	Autorisations spécifiques au plugin	Portées spécifiques aux plugins
`agento11y_manage_conversations`	Agent Observability*	Lister, rechercher et récupérer les conversations LLM depuis Grafana Agent Observability	`grafana-agento11y-app.conversations:read`	N/A
`agento11y_manage_generations`	Agent Observability*	Récupérer les détails de génération LLM et les scores d'évaluation depuis Grafana Agent Observability	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_agents`	Agent Observability*	Lire le catalogue d'agents : lister les agents, obtenir une version d'agent complète, lister l'historique des versions et les agrégats de scores par version	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_evaluators`	Agent Observability*	Gérer les évaluateurs, les modèles d'évaluateurs et le catalogue de juges (lister, obtenir, upsert, forker, tester, supprimer)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` pour les mutations et les tests	N/A
`agento11y_manage_eval_rules`	Agent Observability*	Gérer les règles d'évaluation et les garde-fous (lister, obtenir, créer, mettre à jour, prévisualiser, supprimer)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` pour les mutations et les prévisualisations	N/A
`agento11y_manage_eval_collections`	Agent Observability*	Gérer les conversations enregistrées et les collections qui les regroupent (lister, obtenir, enregistrer, créer, mettre à jour, supprimer, ajouter et retirer des membres)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` pour les mutations	N/A
`agento11y_manage_experiments`	Observabilité des agents*	Lire les expériences hors ligne, leurs essais, scores, métadonnées d'artefacts et facettes de filtrage ; mettre à jour et annuler une expérience	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` pour les mutations	N/A
`agento11y_manage_test_suites`	Observabilité des agents*	Gérer les suites de tests que les expériences hors ligne exécutent, leurs versions et leurs cas de test (lister, obtenir, créer, mettre à jour, brouillon, publier, upsert, supprimer)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` pour les mutations	N/A
`ask_assistant`	Assistant*	Envoyer une invite à Grafana Assistant et renvoyer la réponse texte complète (multi-tours via `contextId`)	Autorisations spécifiques au plugin	Scopes spécifiques au plugin
`generate_deeplink`	Navigation	Générer des URL de liens profonds précises pour les ressources Grafana	Aucune (génération d'URL en lecture seule)	N/A
`get_annotations`	Annotations	Récupérer les annotations avec des filtres	`annotations:read`	`annotations:*` ou `annotations:id:123`
`create_annotation`	Annotations	Créer une nouvelle annotation (format standard ou Graphite)	`annotations:write`	`annotations:*`
`update_annotation`	Annotations	Mettre à jour des champs spécifiques d'une annotation (mise à jour partielle)	`annotations:write`	`annotations:*`
`delete_annotation`	Annotations	Supprimer une annotation par ID	`annotations:delete`	`annotations:*`
`get_annotation_tags`	Annotations	Lister les tags d'annotations avec filtrage optionnel	`annotations:read`	`annotations:*`
`list_snapshots`	Instantané	Lister les instantanés de tableaux de bord avec requête optionnelle et filtres de limite	`dashboards:read`	`dashboards:*` ou `dashboards:uid:abc123`
`get_snapshot`	Instantané	Obtenir les métadonnées d'un instantané et la charge utile du tableau de bord par clé d'instantané	`dashboards:read`	`dashboards:*` ou `dashboards:uid:abc123`
`create_snapshot`	Instantané	Créer un instantané de tableau de bord à partir d'une charge utile complète de tableau de bord	`dashboards:write`	`dashboards:*` ou `dashboards:uid:abc123`
`delete_snapshot`	Instantané	Supprimer un instantané de tableau de bord par clé d'instantané	`dashboards:write`	`dashboards:*` ou `dashboards:uid:abc123`
`get_panel_image`	Rendu	Rendre un tableau de bord ou un panneau stocké — ou un aperçu de provisionnement depuis une branche de dépôt — en image PNG	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	Provisionnement	Lister les dépôts de provisionnement (par ex. sources git-sync) avec leur URL source, branche, état de synchronisation et santé	`provisioning.repositories:read`	N/A
`validate_provisioning_file`	Provisionnement	Appliquer en simulation un fichier depuis un dépôt de provisionnement et signaler les erreurs de validation d'admission	`provisioning.repositories:read`	N/A
`search_docs`	Documentation	Rechercher dans la documentation Grafana ou lister les groupes de produits (omettre la requête pour lister les produits)	Aucune (grafana.com/docs public)	N/A
`get_doc`	Documentation	Récupérer une page de documentation ; définir outline_only pour les titres, ou section pour une récupération limitée	Aucune (grafana.com/docs public)	N/A
* Désactivé par défaut. Ajoutez la catégorie à `--enabled-tools` pour activer.

Référence des indicateurs CLI

Le binaire mcp-grafana prend en charge divers indicateurs de ligne de commande pour la configuration :

Options de transport :

-t, --transport : Type de transport (stdio, sse ou streamable-http) - défaut : stdio
--address : L'hôte et le port pour le serveur SSE/streamable-http - défaut : localhost:8000
--base-path : Chemin de base pour le serveur SSE/streamable-http. /healthz et /metrics sont toujours servis à la racine du serveur, pas sous ce préfixe — ce sont des points de terminaison internes uniquement pour les sondes et les scrapers, et les maintenir hors du préfixe d'application facilite l'exposition de l'API via un proxy inverse sans les exposer également
--endpoint-path : Chemin du point de terminaison pour le serveur streamable-http, ajouté à --base-path - défaut : /mcp
--server-name : Nom du serveur utilisé dans la poignée de main MCP et OTel service.name - défaut : mcp-grafana. Remplace la variable d'environnement GRAFANA_MCP_SERVER_NAME
--instructions-append : Texte ajouté aux instructions du serveur renvoyées aux clients MCP lors de l'initialisation, afin que chaque agent connecté le voie

Sécurité du transport HTTP (SSE / streamable-http uniquement) :

La validation Host/Origin est appliquée sur chaque route de l'écouteur MCP — /sse, /mcp et /healthz / /metrics lorsqu'ils partagent cet écouteur — donc un navigateur de rebinding DNS ne peut atteindre aucun d'entre eux. Le transport stdio n'est pas affecté. --healthz-address et --metrics-address démarrent un écouteur séparé qui n'est pas enveloppé.

--allowed-hosts : Liste d'autorisation séparée par des virgules des valeurs d'en-tête Host. Par défaut, les variantes de bouclage de --address (par exemple localhost:8000,127.0.0.1:8000,[::1]:8000). Une valeur qui se parse en vide (non définie, ,, ,, etc.) retombe également sur les valeurs par défaut afin qu'une faute de frappe ne puisse pas désactiver silencieusement la vérification. Les requêtes avec un en-tête Host hors de la liste d'autorisation sont rejetées avec 403. Passez * pour désactiver la validation Host — sûr uniquement lorsqu'un proxy inverse de confiance valide Host. Les sondes K8s httpGet et les scrapes externes /metrics nécessiteront soit un nom d'hôte explicite dans cette liste, *, une sonde tcpSocket, ou un port séparé (--healthz-address / --metrics-address).
--allowed-origins : Liste d'autorisation séparée par des virgules des valeurs d'en-tête Origin. Vide par défaut — toute requête portant un en-tête Origin est rejetée (les navigateurs envoient toujours un pour les requêtes cross-origin, et aucun navigateur ne devrait appeler ce serveur directement). Définissez une liste explicite pour autoriser les clients basés sur navigateur, ou * pour désactiver la vérification.
--allow-grafana-url-override : Activer la sélection X-Grafana-URL. Retombe sur GRAFANA_ALLOW_URL_OVERRIDE ; désactivé par défaut. Sans liste d'autorisation, les appelants peuvent sélectionner n'importe quelle URL HTTP(S) que le serveur peut atteindre.
--allowed-grafana-urls : Liste d'autorisation facultative séparée par des virgules des URL de base Grafana exactes pour les remplacements d'URL. Retombe sur GRAFANA_ALLOWED_URLS. Nécessite --allow-grafana-url-override ; un indicateur vide explicite désactive une liste héritée.

Authentification de l'appelant (SSE / streamable-http uniquement) :

Exiger facultativement que les clients MCP s'authentifient au serveur. Cela est séparé des identifiants que le serveur utilise pour atteindre Grafana. Stdio n'est pas affecté.

--server-auth-token : Jeton Bearer que les appelants doivent envoyer comme Authorization: Bearer <token>. Retombe sur la variable d'environnement MCP_GRAFANA_SERVER_TOKEN. Lorsqu'il est défini, les requêtes sans jeton valide sont rejetées avec 401 avant l'exécution de tout outil. Préférez la variable d'environnement afin que le secret ne soit pas visible dans les arguments du processus.

L'authentification de l'appelant n'est appliquée que lorsque --server-auth-token est défini. Lorsqu'il ne l'est pas et que le serveur se lie à une adresse non-bouclage, le serveur démarre mais journalise une erreur de sécurité — émise au niveau de journal error afin qu'elle ne soit pas cachée par --log-level (bouclage et stdio ne sont pas affectés) ; une future version majeure en fera une erreur de démarrage. Utilisez TLS (ou terminaison TLS) chaque fois que l'authentification de l'appelant est activée sur une adresse non-bouclage. Lorsque l'authentification de l'appelant est activée, l'en-tête Authorization validé est supprimé avant que les requêtes n'atteignent Grafana ; combiner --server-auth-token avec GRAFANA_FORWARD_HEADERS=Authorization est rejeté au démarrage.

Remplacements d'URL Grafana (SSE / streamable-http uniquement) :

[!WARNING] Les remplacements d'URL permettent aux appelants MCP de sélectionner des destinations HTTP(S) sortantes. Une liste d'autorisation limite les URL mais n'authentifie pas les appelants ni ne lie les jetons aux cibles.

Déployez derrière un proxy d'authentification qui autorise chaque cible, remplace les en-têtes d'URL et de jeton fournis par le client, et fournit le jeton correspondant. Restreignez l'accès réseau sortant du serveur aux destinations approuvées.

Sans liste d'autorisation, un faux jeton de requête peut provoquer des requêtes vers tout service HTTP(S) accessible, y compris les services internes et de métadonnées.

Définissez GRAFANA_ALLOW_URL_OVERRIDE=true (ou --allow-grafana-url-override) pour activer la sélection pour une grande flotte. Pour restreindre les destinations, définissez également GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana (ou --allowed-grafana-urls).

Envoyez ces en-têtes sur chaque requête MCP qui sélectionne une cible :

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

Si --server-auth-token est configuré, envoyez également Authorization: Bearer <MCP caller token>. Cela authentifie auprès du serveur MCP et est séparé de X-Grafana-Service-Account-Token, qui est pour l'instance Grafana sélectionnée. Votre proxy peut envoyer un jeton Grafana différent pour chaque instance ; le serveur ne partage jamais un jeton configuré entre elles. L'en-tête obsolète X-Grafana-API-Key fonctionne également. Un en-tête d'URL sans jeton Grafana de requête est rejeté. Utilisez TLS pour les requêtes entrantes car elles transportent des jetons.

La liste d'autorisation correspond aux URL de base exactes, y compris le schéma, le port et le chemin ; les caractères génériques ne sont pas pris en charge. L'authentification Grafana n'est pas une défense SSRF.

Pour une URL sélectionnée, le serveur n'utilise pas GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, GRAFANA_API_KEY, l'authentification de base d'environnement, GRAFANA_EXTRA_HEADERS ou les certificats clients. La vérification TLS reste activée même si --tls-skip-verify est défini ; un fichier CA configuré s'applique toujours. Les en-têtes explicitement transférés depuis cette requête s'appliquent toujours. Les redirections et autres requêtes API Grafana en dehors de l'URL de base sélectionnée sont bloquées. Les requêtes sans X-Grafana-URL conservent le comportement habituel de GRAFANA_URL et des identifiants d'environnement. Cette option s'applique à SSE et streamable HTTP uniquement. Pour SSE, incluez les deux en-têtes de sélection sur chaque POST de message ; les en-têtes sur le GET SSE initial ne se reportent pas aux appels d'outils.

Débogage et journalisation :

--debug : Activer le mode débogage pour une journalisation détaillée des requêtes/réponses HTTP
--log-level : Niveau de journal (debug, info, warn, error) - défaut : info

Options du client Grafana :

--grafana-timeout : Limite de temps pour les requêtes faites par le client Grafana. Accepte les chaînes de durée Go (par exemple 10s, 500ms) - défaut : 10s
--include-args-in-spans : Inclure les arguments d'appel d'outil dans les spans OpenTelemetry. À activer uniquement dans les environnements non-production ou lorsque les arguments sont connus pour ne pas contenir de PII - défaut : false

Observabilité :

--metrics : Activer le point de terminaison de métriques Prometheus à /metrics
--metrics-address : Adresse séparée pour le serveur de métriques (par exemple :9090). Si vide, les métriques sont servies sur le serveur principal
--healthz-address : Adresse séparée pour /healthz (par exemple :8080). Si vide, /healthz est servi sur le serveur principal. Partage un écouteur avec --metrics-address lorsque les deux adresses correspondent. Les écouteurs latéraux ignorent la validation Host/Origin.
--slow-request-threshold : Journaliser un événement lorsque toute requête MCP (invocation d'outil, liste, lecture de ressource, etc.) prend plus longtemps que cette durée. Accepte les chaînes de durée Go (par exemple 500ms, 5s). Le défaut 0 désactive la journalisation des requêtes lentes. Voir la section Journalisation des requêtes lentes.
--slow-request-log-level : Niveau de journal pour les événements de requêtes lentes (info ou warn) - défaut : warn.

Statistiques d'utilisation anonymes :

--usage-stats : Rapport de statistiques d'utilisation anonymes : enabled, disabled ou log (imprimer le rapport qui serait envoyé sur stderr et n'envoyer rien). Remplace la variable d'environnement GRAFANA_USAGE_STATS, qui à son tour remplace DO_NOT_TRACK ; toute valeur non reconnue désactive le rapport. Voir la section Statistiques d'utilisation anonymes.

Gestion des sessions :

--session-idle-timeout-minutes : Délai d'inactivité de session en minutes. Les sessions sans activité pendant cette durée sont automatiquement récupérées - défaut : 30. Définissez sur 0 pour désactiver la récupération de session. Pertinent uniquement pour les transports SSE et streamable-http. Configuration des outils :
--enabled-tools : Liste séparée par des virgules des catégories activées - par défaut : toutes les catégories sauf admin, agento11y, assistant, athena, clickhouse, cloudlogging, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery et snowflake. Pour activer les catégories désactivées, ajoutez-les à la liste (par exemple, "search,datasource,...,snowflake")
--max-loki-log-limit : Nombre maximal de lignes de logs retournées par appel query_loki_logs - par défaut : 100. Remarque : définissez ce paramètre au moins 1 en dessous du max_entries_limit_per_query côté serveur de Loki pour permettre la détection de troncature (l'outil demande limit+1 en interne pour détecter si plus de données existent).
--loki-guardrail-mode : Garde-fou de coût des requêtes Loki pour query_loki_logs - par défaut : off. Loki n'applique pas max_query_bytes_read sur les requêtes de logs sans filtre de ligne, donc un sélecteur large sur une plage étendue peut analyser des téraoctets ; le garde-fou exige un sélecteur de flux sélectif, plafonne la plage temporelle effective (y compris les durées de vecteur de plage comme [30d]) et pré-vérifie l'estimation d'octets de l'index/stats de Loki avant d'exécuter la requête. shadow journalise les requêtes qui seraient bloquées mais les laisse s'exécuter (il paie toujours l'aller-retour index/stats) ; enforce les rejette avec des conseils de réécriture sur lesquels le LLM peut agir. Sur VictoriaLogs, le garde-fou s'applique uniquement aux requêtes en forme de sélecteur ({...}) — lorsqu'aucun sélecteur ne peut être analysé (la forme LogsQL normale sans accolades), la requête passe entièrement, et la vérification du budget d'octets ne s'applique jamais (aucune estimation d'index économique). Repli d'environnement : GRAFANA_LOKI_GUARDRAIL_MODE.
--loki-guardrail-max-bytes : Nombre maximal d'octets qu'un seul appel query_loki_logs peut analyser, estimé via l'API index/stats de Loki - par défaut : 107374182400 (100 Gio). 0 désactive la vérification du budget d'octets. Repli d'environnement : GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.
--loki-guardrail-max-range : Plage temporelle effective maximale pour un seul appel query_loki_logs, y compris les durées de vecteur de plage - par défaut : 24h. Accepte les chaînes de durée Go. 0 désactive la vérification de plage. Repli d'environnement : GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.
--loki-enforced-matchers : Correspondances d'étiquettes LogQL combinées par ET dans chaque requête Loki native pour restreindre les flux de logs pouvant être lus (par exemple, environment=~"prod|staging"). Nécessite --disable-api. Voir Application des requêtes Loki.
--loki-label-enumeration-fallback : Ce que font les outils d'énumération d'étiquettes lorsque les correspondances négatives appliquées ne peuvent pas les limiter : reject (par défaut) ou unfiltered. Voir Application des requêtes Loki.
--disable-search : Désactiver les outils de recherche
--disable-datasource : Désactiver les outils de source de données
--disable-incident : Désactiver les outils d'incident
--disable-prometheus : Désactiver les outils Prometheus
--disable-write : Désactiver les outils d'écriture (opérations de création/mise à jour)
--disable-query : Désactiver les outils de requête (outils qui exécutent une requête contre une source de données) ; les outils de métadonnées et de découverte restent disponibles
--enable-query : Conserver les outils de requête SQL bruts (query_sql, query_influxdb) enregistrés même sous --disable-write. Équivalent à --enable-write-tools=query_sql,query_influxdb ; conservé comme raccourci pour ce cas courant.
--enable-write-tools : Liste séparée par des virgules des noms d'outils individuels à conserver enregistrés même sous --disable-write, pour les outils dont le comportement d'écriture est suffisamment limité pour être réactivé indépendamment (par exemple, find_error_pattern_logs,find_slow_requests). N'a aucun effet sur un outil dont toute la catégorie est désactivée, par exemple via --disable-sift.
--disable-loki : Désactiver les outils Loki
--disable-elasticsearch : Désactiver les outils Elasticsearch et OpenSearch
--disable-quickwit : Désactiver les outils Quickwit
--disable-influxdb : Désactiver les outils InfluxDB
--disable-alerting : Désactiver les outils d'alerting
--disable-dashboard : Désactiver les outils de tableaux de bord
--disable-oncall : Désactiver les outils OnCall
--disable-asserts : Désactiver les outils Asserts
--disable-sift : Désactiver les outils Sift
--disable-admin : Désactiver les outils d'administration
--disable-pyroscope : Désactiver les outils Pyroscope
--disable-navigation : Désactiver les outils de navigation
--disable-rendering : Désactiver les outils de rendu (export d'images de panneaux/tableaux de bord)
--disable-snapshot : Désactiver les outils de capture instantanée
--disable-cloudwatch : Désactiver les outils CloudWatch
--disable-cloudlogging : Désactiver les outils Google Cloud Logging
--disable-examples : Désactiver les outils d'exemples de requêtes
--disable-sql : Désactiver les outils de source de données SQL (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). Les alias --disable-clickhouse, --disable-snowflake, --disable-athena fonctionnent également.
--disable-runpanelquery : Désactiver les outils d'exécution de requêtes de panneaux
--disable-graphite : Désactiver les outils Graphite
--disable-provisioning : Désactiver les outils de provisionnement
--disable-agento11y : Désactiver les outils Agent Observability
--disable-assistant : Désactiver les outils Grafana Assistant
--disable-docs : Désactiver les outils de documentation

Mode lecture seule

Le drapeau --disable-write offre un moyen d'exécuter le serveur MCP en mode lecture seule, empêchant toute opération d'écriture sur votre instance Grafana. Cela est utile pour les scénarios où vous souhaitez fournir un accès sécurisé en lecture seule, tels que :

Utilisation de comptes de service avec des autorisations limitées en lecture seule
Fourniture d'assistants IA avec des données d'observabilité sans capacités de modification
Exécution dans des environnements de production où l'accès en écriture doit être restreint
Scénarios de test et de développement où vous souhaitez empêcher les modifications accidentelles

Lorsque --disable-write est activé, les opérations d'écriture suivantes sont désactivées :

Outils de tableaux de bord :

update_dashboard

Outils de dossiers :

create_folder

Outils d'incident :

create_incident
add_activity_to_incident
update_incident

Outils d'alerting :

alerting_manage_rules (opérations de création, mise à jour, suppression)
alerting_manage_silences (opérations de création, mise à jour, suppression)

Outils OnCall :

update_alert_group

Outils d'annotation :

create_annotation
update_annotation
delete_annotation

Outils Sift :

find_error_pattern_logs (crée des investigations)
find_slow_requests (crée des investigations)

Ceux-ci créent uniquement des enregistrements d'investigation Sift éphémères via l'API Sift — ils ne touchent jamais un tableau de bord, une alerte ou une source de données Grafana. Sans eux, list_sift_investigations/get_sift_investigation/get_sift_analysis n'ont rien à lister ou à obtenir. Passez --enable-write-tools=find_error_pattern_logs,find_slow_requests pour les conserver enregistrés sous --disable-write.

Outils de capture instantanée :

create_snapshot
delete_snapshot

Outils de requête SQL bruts :

Ceux-ci exécutent toute requête que vous leur donnez sans l'inspecter, ils peuvent donc écrire lorsque les identifiants de la source de données le permettent — query_sql exécutera un DROP TABLE, query_influxdb exécutera un DELETE. Le mode lecture seule les supprime donc. Passez --enable-query pour les conserver lorsque les identifiants de la source de données sont connus pour être en lecture seule.

query_sql
query_influxdb

Outils Agent Observability :

agento11y_manage_evaluators (opérations upsert, suppression, fork, test d'évaluateur)
agento11y_manage_eval_rules (opérations de création, mise à jour, suppression, aperçu de règles et de garde-fous)
agento11y_manage_eval_collections (enregistrer et supprimer des conversations enregistrées ; créer, mettre à jour, supprimer des collections ; ajouter et supprimer des membres de collection)
agento11y_manage_experiments (opérations de mise à jour et d'annulation d'expériences)
agento11y_manage_test_suites (créer et mettre à jour des suites de tests ; créer et publier des versions ; upsert et supprimer des cas de test)

Toutes les opérations de lecture restent disponibles, vous permettant d'interroger les tableaux de bord, d'exécuter des requêtes PromQL/LogQL, de lister les ressources et de récupérer des données. Les langages de requête qui ne peuvent pas exprimer une écriture — PromQL, LogQL, TraceQL, le DSL Elasticsearch, Graphite, CloudWatch — conservent leurs outils de requête en mode lecture seule ; seuls les outils SQL bruts listés ci-dessus sont supprimés.

Mode sans requête

Le drapeau --disable-query supprime tout outil qui exécute une requête contre une source de données, tout en laissant les outils de métadonnées et de découverte en place. Cela est utile lorsque vous souhaitez un assistant capable d'explorer ce qui existe — sources de données, tableaux de bord, noms de métriques, étiquettes, schémas de tables — sans exécuter de requêtes potentiellement coûteuses ou révélatrices de données, par exemple lorsque le compte de service dispose de datasources:read mais pas de datasources:query.

C'est le plus strict des trois paramètres de requête, et il l'emporte sur --enable-query :

Drapeaux	Outils de requête sûrs (`query_prometheus`, `query_loki_logs`, `run_panel_query`, …)	Outils de requête SQL bruts (`query_sql`, `query_influxdb`)
(aucun)	enregistrés	enregistrés
`--disable-write`	enregistrés	non enregistrés
`--disable-write --enable-query`	enregistrés	enregistrés
`--disable-query`	non enregistrés	non enregistrés
`--disable-query --enable-query`	non enregistrés	non enregistrés

Lorsque --disable-query est activé, les outils suivants ne sont pas enregistrés :

Outils Prometheus :

query_prometheus
query_prometheus_histogram

Outils Loki :

query_loki_logs
query_loki_patterns

query_loki_stats et analyze_loki_labels restent enregistrés : les deux envoient un sélecteur à la source de données, mais ils lisent l'index et renvoient des comptages de flux, de morceaux et d'octets plutôt que le contenu des logs.

Outils Elasticsearch/OpenSearch et Quickwit :

query_elasticsearch
query_quickwit

Outils InfluxDB (également supprimés par --disable-write, voir ci-dessus) :

query_influxdb

Outils de source de données SQL (également supprimés par --disable-write, voir ci-dessus) :

query_sql

Outils Graphite :

query_graphite
query_graphite_density

Outils CloudWatch :

query_cloudwatch

Outils Google Cloud Logging :

query_cloud_logging

Outils Pyroscope :

query_pyroscope

Outils d'exécution de requêtes de panneaux :

run_panel_query

Les catégories elasticsearch, quickwit, influxdb et runpanelquery ne contiennent rien d'autre, elles n'enregistrent donc aucun outil lorsque les requêtes sont désactivées. Les outils frères de chaque autre catégorie — list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects, et ainsi de suite — restent disponibles.

Notez que --disable-query contrôle les outils de requête et le chemin POST vers grafana_api_request-/api/ds/query, mais ne surveille pas chaque route vers une source de données. En mode lecture seule, grafana_api_request autorise POST vers /api/ds/query uniquement lorsque les outils de requête sont activés (même contrôle que les outils SQL bruts — bloqué par --disable-write sauf si --enable-query le remplace). get_panel_image, qui rend un panneau côté serveur, n'est pas affecté.

Configuration TLS client (pour les connexions Grafana) :

--tls-cert-file : Chemin vers le fichier de certificat TLS pour l'authentification client
--tls-key-file : Chemin vers le fichier de clé privée TLS pour l'authentification client
--tls-ca-file : Chemin vers le fichier de certificat CA TLS pour la vérification du serveur
--tls-skip-verify : Ignorer la vérification du certificat TLS (non sécurisé)

Configuration TLS serveur (transport streamable-http uniquement) :

--server.tls-cert-file : Chemin vers le fichier de certificat TLS pour le serveur HTTPS
--server.tls-key-file : Chemin vers le fichier de clé privée TLS pour le serveur HTTPS

Utilisation

Ce serveur MCP fonctionne avec les instances Grafana locales et Grafana Cloud. Pour Grafana Cloud, utilisez l'URL de votre instance (par exemple, https://myinstance.grafana.net) au lieu de http://localhost:3000 dans les exemples de configuration ci-dessous.

Si vous utilisez l'authentification par jeton de compte de service, créez un compte de service dans Grafana avec suffisamment d'autorisations pour utiliser les outils que vous souhaitez utiliser, générez un jeton de compte de service et copiez-le dans le presse-papiers pour l'utiliser dans le fichier de configuration. Suivez la documentation sur les comptes de service Grafana pour plus de détails sur la création de jetons de compte de service. Astuce : Si vous n'êtes pas à l'aise avec la configuration de portées RBAC fines, une option plus simple (mais moins restrictive) consiste à attribuer le rôle intégré Editor au compte de service. Cela accorde un accès large en lecture/écriture qui couvre la plupart des opérations du serveur MCP — utilisez-le lorsque la commodité l'emporte sur les exigences strictes de moindre privilège.

Remarque : La variable d'environnement GRAFANA_API_KEY est obsolète et sera supprimée dans une version future. Veuillez migrer vers l'utilisation de GRAFANA_SERVICE_ACCOUNT_TOKEN à la place. L'ancien nom de variable continuera de fonctionner pour la rétrocompatibilité mais affichera des avertissements d'obsolescence.

Lecture du jeton de compte de service depuis un fichier

Au lieu de passer le jeton en ligne via GRAFANA_SERVICE_ACCOUNT_TOKEN, vous pouvez pointer GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE vers un chemin de fichier contenant le jeton. Le fichier est relu à chaque requête, de sorte que les jetons renouvelés sont détectés automatiquement sans redémarrer le serveur.

Cela est particulièrement utile dans Kubernetes, où un Secret monté en tant que volume est mis à jour sur place lorsque le Secret sous-jacent change (généralement en environ 1 minute). Combiné avec le cache client par requête — qui est indexé sur la valeur du jeton — un jeton renouvelé produit de manière transparente un nouveau client sans redémarrage de pod et sans interruption de service :

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

Les espaces environnants (y compris un saut de ligne final) sont supprimés du contenu du fichier. Si à la fois GRAFANA_SERVICE_ACCOUNT_TOKEN et GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE sont définis, le jeton en ligne a priorité.

Prise en charge multi-organisation

Vous pouvez spécifier avec quelle organisation interagir en utilisant soit :

Variable d'environnement : Définissez GRAFANA_ORG_ID sur l'ID numérique de l'organisation
En-tête HTTP : Définissez X-Grafana-Org-Id lors de l'utilisation des transports SSE ou HTTP streamable (l'en-tête a priorité sur la variable d'environnement — ce qui signifie que vous pouvez également définir une organisation par défaut).

Lorsqu'un ID d'organisation est fourni, le serveur MCP définira l'en-tête X-Grafana-Org-Id sur toutes les requêtes à Grafana, garantissant que les opérations sont effectuées dans le contexte de l'organisation spécifiée.

Sélection dynamique d'organisation (par appel)

Les options ci-dessus fixent l'organisation pour toute la connexion. Pour permettre à une seule connexion de cibler différentes organisations par appel d'outil, démarrez le serveur avec le drapeau --dynamic-multi-org. Ceci est désactivé par défaut.

Lorsqu'il est activé, chaque outil accepte un argument optionnel orgId qui remplace l'organisation de la connexion pour cet appel (en pilotant à la fois l'en-tête X-Grafana-Org-Id et, pour les API de la plateforme d'applications, l'espace de noms Kubernetes résolu). Les outils de source de données proxy sont en outre découverts dans chaque organisation à laquelle les identifiants peuvent accéder. Les appels qui omettent orgId utilisent l'organisation par défaut de la connexion.

Cela ne fonctionne que pour les identifiants appartenant à plus d'une organisation (par exemple, un utilisateur ou une identité pour le compte d'autrui) ; un jeton de compte de service reste lié à son organisation unique. Utilisez l'outil user_info pour découvrir quelles valeurs orgId sont valides.

Exemple avec ID d'organisation :

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

En-têtes HTTP personnalisés

Vous pouvez ajouter des en-têtes HTTP arbitraires à toutes les requêtes API Grafana en utilisant la variable d'environnement GRAFANA_EXTRA_HEADERS. La valeur doit être un objet JSON mappant les noms d'en-têtes à des valeurs.

Exemple avec en-têtes personnalisés :

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

Proxy SOCKS5

Vous pouvez router toutes les requêtes que ce serveur fait à Grafana via un proxy SOCKS5 en utilisant la variable d'environnement GRAFANA_SOCKS5_PROXY. Le proxy est limité au trafic Grafana de ce serveur : il ne modifie pas les variables globales HTTP_PROXY/HTTPS_PROXY, et lorsqu'il est défini, il remplace leur sélection de proxy uniquement pour les transports Grafana, sans affecter les autres serveurs MCP ou votre session shell. Lorsqu'il n'est pas défini, le comportement est inchangé.

L'URL doit utiliser le schéma socks5:// ou socks5h:// (Go les traite de manière identique : la résolution du nom d'hôte est déléguée au proxy) et peut inclure des identifiants, par exemple socks5://user:pass@127.0.0.1:1080.

Exemple :

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

Une URL de proxy invalide est une erreur au démarrage, et si la construction d'une connexion proxy échoue à l'exécution, le serveur échoue de manière sécurisée plutôt que d'envoyer silencieusement le trafic Grafana directement.

Transfert des en-têtes du client (SSE/HTTP streamable uniquement)

Lorsque le serveur MCP s'exécute derrière une passerelle ou un proxy inverse qui gère le SSO (par exemple, un AWS ALB avec OIDC), le cookie de session de chaque utilisateur doit atteindre Grafana afin qu'il puisse associer la requête à l'utilisateur authentifié. La variable d'environnement GRAFANA_FORWARD_HEADERS active cela en spécifiant une liste d'autorisation séparée par des virgules des noms d'en-têtes à copier de la requête HTTP entrante vers chaque requête API Grafana sortante.

Cela ne s'applique que lors de l'utilisation des transports SSE (-t sse) ou HTTP streamable (-t streamable-http). Cela n'a aucun effet en mode stdio.

Exemple : transférer le cookie de session

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

Vous pouvez transférer plusieurs en-têtes en les séparant par des virgules :

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

Les en-têtes transférés sont fusionnés avec tous les en-têtes définis dans GRAFANA_EXTRA_HEADERS. Si un nom d'en-tête apparaît dans les deux, la valeur de la requête entrante a priorité pour cette requête.

Les en-têtes de contexte de trace (traceparent, tracestate, baggage) sont l'exception : le serveur propage lui-même le contexte de trace, donc une valeur transférée ne remplace jamais celle qu'il injecte. Voir observabilité.

Vous avez plusieurs options pour installer mcp-grafana :
- uvx (recommandé) : Si vous avez uv installé, aucune configuration supplémentaire n'est nécessaire — uvx téléchargera et exécutera automatiquement le serveur :
```
uvx mcp-grafana
```
- Image Docker : Utilisez l'image Docker pré-construite depuis Docker Hub.
  
  Important : Le point d'entrée de l'image Docker est configuré pour exécuter le serveur MCP en mode SSE par défaut, mais la plupart des utilisateurs voudront utiliser le mode STDIO pour une intégration directe avec des assistants IA comme Claude Desktop :
  1. Mode STDIO : Pour le mode stdio, vous devez explicitement remplacer la valeur par défaut avec -t stdio et inclure le drapeau -i pour garder stdin ouvert :
```
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
```
  Remarque — sécuriser les modes réseau : Dans les modes SSE et HTTP streamable, le conteneur lie une adresse non-loopback (0.0.0.0:8000). Sans jeton d'appelant, le serveur démarre mais journalise une erreur de sécurité (au niveau de journal error, donc elle n'est pas masquée par --log-level ; et il refusera de démarrer dans une future version majeure). Définissez MCP_GRAFANA_SERVER_TOKEN pour exiger un Authorization: Bearer <token> des clients (recommandé). Le mode STDIO n'est pas affecté. Voir Authentification de l'appelant.
  1. Mode SSE : Dans ce mode, le serveur s'exécute comme un serveur HTTP auquel les clients se connectent. Vous devez exposer le port 8000 en utilisant le drapeau -p :
```
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. Mode HTTP streamable : Dans ce mode, le serveur fonctionne comme un processus indépendant qui peut gérer plusieurs connexions clientes. Vous devez exposer le port 8000 en utilisant le drapeau -p : Pour ce mode, vous devez explicitement remplacer la valeur par défaut avec -t streamable-http
```
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
```
  Pour le mode HTTP streamable HTTPS avec certificats TLS serveur :
```
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
```
- Télécharger le binaire : Téléchargez la dernière version de mcp-grafana depuis la page des versions et placez-la dans votre $PATH.
- Compiler depuis la source : Si vous avez une chaîne d'outils Go installée, vous pouvez également la compiler et l'installer depuis la source, en utilisant la variable d'environnement GOBIN pour spécifier le répertoire où le binaire doit être installé. Cela devrait également être dans votre $PATH.
```
GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
```
- Déployer sur Kubernetes avec Helm : utilisez le chart Helm du dépôt helm-charts de Grafana
```
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
```

Ajoutez la configuration du serveur à votre fichier de configuration client. Par exemple, pour Claude Desktop :

Si vous utilisez uvx :

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

Si vous utilisez le binaire :

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

Remarque : si vous voyez Error: spawn mcp-grafana ENOENT dans Claude Desktop, vous devez spécifier le chemin complet vers mcp-grafana.

Si vous utilisez 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"
      }
    }
  }
}

Remarque : L'argument -t stdio est essentiel ici car il remplace le mode SSE par défaut dans l'image Docker.

Utilisation de VSCode avec un serveur MCP distant

Si vous utilisez VSCode et exécutez le serveur MCP en mode SSE (ce qui est la valeur par défaut lors de l'utilisation de l'image Docker sans remplacer le transport), assurez-vous que votre .vscode/settings.json inclut ce qui suit :

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

Pour le mode HTTP streamable HTTPS avec certificats TLS serveur :

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

Mode débogage

Vous pouvez activer le mode débogage pour le transport Grafana en ajoutant le drapeau -debug à la commande. Cela fournira une journalisation détaillée des requêtes et réponses HTTP entre le serveur MCP et l'API Grafana, ce qui peut être utile pour le dépannage.

Pour utiliser le mode débogage avec la configuration Claude Desktop, mettez à jour votre configuration comme suit :

Si vous utilisez le binaire :

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

Si vous utilisez 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>"
      }
    }
  }
}

Remarque : Comme avec la configuration standard, l'argument -t stdio est requis pour remplacer le mode SSE par défaut dans l'image Docker.

Configuration TLS

Si votre instance Grafana est derrière mTLS ou nécessite des certificats TLS personnalisés, vous pouvez configurer le serveur MCP pour utiliser des certificats personnalisés. Le serveur prend en charge les options de configuration TLS suivantes :

--tls-cert-file : Chemin vers le fichier de certificat TLS pour l'authentification client
--tls-key-file : Chemin vers le fichier de clé privée TLS pour l'authentification client
--tls-ca-file : Chemin vers le fichier de certificat CA TLS pour la vérification du serveur
--tls-skip-verify : Ignorer la vérification du certificat TLS (non sécurisé, à utiliser uniquement pour les tests)

Exemple avec authentification par certificat client :

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

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

La configuration TLS est appliquée à tous les clients HTTP utilisés par le serveur MCP, y compris :

Le client OpenAPI principal de Grafana
Les clients de source de données Prometheus
Les clients de source de données Loki
Les clients de gestion des incidents
Les clients d'enquête Sift
Les clients d'alerting
Les clients Asserts

Exemples d'utilisation directe en CLI :

Pour les tests avec des certificats auto-signés :

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

Avec authentification par certificat client :

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

Avec certificat CA personnalisé uniquement :

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

Utilisation programmatique :

Si vous utilisez cette bibliothèque de manière programmatique, vous pouvez également créer des fonctions de contexte compatibles TLS :

// 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)

Validation d'URL :

Lors de l'appel de NewGrafanaClient directement (stdio ou construction programmatique), pré-validez les URL pour éviter une panique accessible :

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

Configuration TLS serveur (transport HTTP streamable uniquement)

Lors de l'utilisation du transport HTTP streamable (-t streamable-http), vous pouvez configurer le serveur MCP pour servir HTTPS au lieu de HTTP. Cela est utile lorsque vous devez sécuriser la connexion entre votre client MCP et le serveur lui-même.

Le serveur prend en charge les options de configuration TLS suivantes pour le transport HTTP streamable :

--server.tls-cert-file : Chemin vers le fichier de certificat TLS pour le serveur HTTPS (requis pour TLS)
--server.tls-key-file : Chemin vers le fichier de clé privée TLS pour le serveur HTTPS (requis pour TLS)

Remarque : Ces drapeaux sont complètement séparés des drapeaux TLS client documentés ci-dessus. Les drapeaux TLS client configurent la façon dont le serveur MCP se connecte à Grafana, tandis que ces drapeaux TLS serveur configurent la façon dont les clients se connectent au serveur MCP lors de l'utilisation du transport HTTP streamable.

Exemple avec serveur HTTP streamable HTTPS :

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

Cela démarrerait le serveur MCP sur le port HTTPS 8443. Les clients se connecteraient alors à https://localhost:8443/ au lieu de http://localhost:8000/.

Exemple Docker avec TLS serveur :

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

Point de terminaison de vérification de santé

Lors de l'utilisation des transports SSE (-t sse) ou HTTP streamable (-t streamable-http), le serveur MCP expose un point de terminaison de vérification de santé à /healthz. Ce point de terminaison peut être utilisé par les équilibreurs de charge, les systèmes de surveillance ou les plateformes d'orchestration pour vérifier que le serveur fonctionne et accepte les connexions.

Point de terminaison : GET /healthz

Réponse :

Code de statut : 200 OK
Corps : ok

Exemple d'utilisation :

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

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

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

Remarque : Le point de terminaison de vérification de santé n'est disponible que lors de l'utilisation des transports SSE ou HTTP streamable. Il n'est pas disponible lors de l'utilisation du transport stdio (-t stdio), car stdio n'expose pas de serveur HTTP.

Statistiques d'utilisation anonymes

Le serveur peut signaler des statistiques d'utilisation anonymes à Grafana Labs : quels outils ont été appelés, combien de ces appels ont échoué, et comment le serveur est configuré. Un rapport couvre un processus serveur — pas un utilisateur ni une conversation — et est envoyé toutes les 4 heures plus une fois à l'arrêt. La signalisation est désactivée par défaut dans cette version — le point de réception n'est pas encore actif — et une version ultérieure changera la valeur par défaut pour l'activer avec la même option de désactivation.

Les arguments d'outils, les noms de ressources, les requêtes, les lignes de journal, les messages d'erreur et les identifiants ne sont jamais envoyés. Les indicateurs sont enregistrés uniquement par nom, jamais par valeur, et l'instance Grafana est décrite uniquement comme cloud ou self_hosted — jamais par URL, nom d'hôte, slug de pile ou organisation. Rien n'est par utilisateur, par session ou par client : il n'y a pas d'identifiant de session sur le fil et aucun moyen d'attribuer un appel d'outil à un client particulier.

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

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

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

DO_NOT_TRACK=1 désactive également la signalisation, suivant la convention DO_NOT_TRACK inter-outils. Seul 1 a un effet, il ne peut que désactiver, et --usage-stats et GRAFANA_USAGE_STATS le remplacent tous deux, donc un hôte qui le définit globalement peut toujours réactiver un serveur.

GRAFANA_USAGE_STATS_ENDPOINT change la destination. Ce n'est pas une option de désactivation.

Pour la liste complète des champs, ce qui n'est jamais envoyé, comment lire les données et leurs limites, voir Statistiques d'utilisation anonymes.

Observabilité

Le serveur MCP prend en charge les métriques Prometheus, le tracing distribué OpenTelemetry et l'exportation de journaux OpenTelemetry, suivant les conventions sémantiques OTel MCP. Le tracing et l'exportation de journaux sont configurés via des variables d'environnement standard OTEL_* et fonctionnent avec n'importe quel transport.

Remarque : mcp-grafana ne prend actuellement en charge que le transport OTLP/gRPC pour les traces et les journaux. OTEL_EXPORTER_OTLP_PROTOCOL (et ses variantes _TRACES_PROTOCOL / _LOGS_PROTOCOL) ne sont pas honorés — gRPC est utilisé quoi qu'il arrive.

Métriques

Lorsque vous utilisez les transports SSE ou HTTP streamable, activez les métriques Prometheus avec l'indicateur --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

Métriques disponibles :

Métrique	Type	Description
`mcp_server_operation_duration_seconds`	Histogramme	Durée des opérations MCP (étiquettes : `mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`)
`mcp_server_session_duration_seconds`	Histogramme	Durée des sessions client MCP (étiquettes : `network_transport`, `mcp_protocol_version`)
`http_server_request_duration_seconds`	Histogramme	Durée des requêtes du serveur HTTP (depuis otelhttp)

Remarque : Les métriques ne sont disponibles qu'avec les transports SSE ou HTTP streamable. Elles ne sont pas disponibles avec le transport stdio.

Lorsque le garde-fou de coût Loki (--loki-guardrail-mode) est activé, quatre compteurs supplémentaires enregistrent ses décisions :

Métrique	Type	Description
`mcp_loki_guardrail_admitted_total`	Compteur	Requêtes ayant réussi toutes les vérifications activées (étiquettes : `backend`)
`mcp_loki_guardrail_would_block_total`	Compteur	Requêtes ayant échoué à une vérification en mode `shadow` et exécutées quand même (étiquettes : `backend`, `reason`)
`mcp_loki_guardrail_blocked_total`	Compteur	Requêtes rejetées en mode `enforce` (étiquettes : `backend`, `reason`)
`mcp_loki_guardrail_fail_open_total`	Compteur	Requêtes que le garde-fou n'a pas pu évaluer et a admises (étiquettes : `backend`, `cause`)

reason est l'un de selector, range, bytes ; cause est l'un de unparseable, estimate_failed ; backend est l'un de loki, victorialogs, unknown. Une requête qui déclenche plusieurs vérifications est comptée une fois, étiquetée avec la vérification exécutée en premier (selector, puis range, puis bytes), donc les quatre compteurs partitionnent la population protégée. Voir Observabilité pour savoir comment les lire lors d'un déploiement shadow → enforce.

Les intégrateurs de bibliothèque doivent définir GrafanaConfig.MeterProvider (l'équivalent métrique de GrafanaConfig.Logger) : le garde-fou s'exécute dans un gestionnaire d'outil, donc il n'a pas d'option de constructeur, et un processus qui installe un MeterProvider global noop perdrait autrement chaque enregistrement.

Journalisation des requêtes lentes

L'indicateur --slow-request-threshold émet un événement de journal structuré chaque fois qu'une requête MCP (invocation d'outil, liste, lecture de ressource, etc.) dépasse la durée donnée. Il est utile pour diagnostiquer les requêtes et appels d'outils lents sans se noyer dans le journal de débogage complet.

# 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

L'événement de journal porte ces attributs structurés :

Attribut	Description
`mcp.method`	La méthode MCP (par exemple, `tools/call`, `tools/list`, `resources/read`)
`duration`	Durée de requête observée
`threshold`	Seuil configuré
`tool`	Nom de l'outil (présent uniquement pour les méthodes `tools/call`)
`error`	Valeur d'erreur, lorsque la requête a échoué (contexte au mieux ; le contenu est contrôlé par l'encapsulation d'erreur en amont)
`error.type`	Classification d'erreur à cardinalité bornée (`_OTHER` pour les erreurs non typées)

La journalisation des requêtes lentes fonctionne sur tous les transports (y compris stdio) et ne nécessite pas --metrics. Le seuil par défaut de 0 la désactive entièrement. Les outils proxy passent par tools/call et sont couverts automatiquement.

Tracing

Le tracing distribué est configuré via des variables d'environnement standard OTEL_* et fonctionne indépendamment de l'indicateur --metrics. Lorsque OTEL_EXPORTER_OTLP_ENDPOINT (ou le OTEL_EXPORTER_OTLP_TRACES_ENDPOINT spécifique au signal) est défini, le serveur exporte des traces via 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

Les spans d'appels d'outils suivent la nomenclature semconv (tools/call <tool_name>) et incluent des attributs comme gen_ai.tool.name, mcp.method.name et mcp.session.id. Le serveur prend également en charge la propagation du contexte de trace W3C depuis le champ _meta des requêtes d'appels d'outils.

Journaux

Lorsque OTEL_EXPORTER_OTLP_ENDPOINT (ou le OTEL_EXPORTER_OTLP_LOGS_ENDPOINT spécifique au signal) est défini, le serveur exporte également des journaux structurés via OTLP/gRPC en plus de la sortie stderr en texte brut existante. Le pont otelslog attache automatiquement trace_id et span_id depuis le span actif, donc les enregistrements de journaux sont corrélés avec les traces que le serveur émet déjà.

Les traces et les journaux résolvent leurs points de terminaison indépendamment, donc les deux signaux peuvent être activés séparément : définir uniquement OTEL_EXPORTER_OTLP_TRACES_ENDPOINT active le tracing sans exportation de journaux, définir uniquement OTEL_EXPORTER_OTLP_LOGS_ENDPOINT active l'exportation de journaux sans tracing, et le OTEL_EXPORTER_OTLP_ENDPOINT générique active les deux.

Si vous utilisez le OTEL_EXPORTER_OTLP_ENDPOINT générique mais souhaitez désactiver l'exportation de journaux (par exemple, votre backend ne prend pas en charge le LogsService), définissez :

OTEL_LOGS_EXPORTER=none

Cela empêche le serveur de créer un exportateur de journaux OTLP quelle que soit la configuration du point de terminaison, évitant des erreurs comme unknown service opentelemetry.proto.collector.logs.v1.LogsService.

La journalisation stderr est inchangée lorsque la journalisation OTLP est activée ; vous pouvez continuer à vous fier aux journaux de conteneur ou rediriger stderr vers /dev/null si vous préférez.

# 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

Le transport est OTLP/gRPC (port par défaut 4317). Les journaux peuvent être envoyés directement à tout backend géré qui accepte OTLP/gRPC — par exemple, Grafana Cloud — en pointant OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (ou le OTEL_EXPORTER_OTLP_ENDPOINT générique) vers le point de terminaison gRPC distant et en fournissant l'authentification via OTEL_EXPORTER_OTLP_LOGS_HEADERS (ou OTEL_EXPORTER_OTLP_HEADERS), en miroir de l'exemple de tracing ci-dessus. Un collecteur OTel local est optionnel — utile pour la diffusion, le traitement par lots ou le routage multi-backend, mais pas requis.

Les variantes spécifiques au signal 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 et OTEL_EXPORTER_OTLP_LOGS_COMPRESSION sont honorées et remplacent leurs équivalents génériques OTEL_EXPORTER_OTLP_* — voir la spécification de l'exportateur OTel pour la liste complète et les règles de précédence.

Si le collecteur configuré est inaccessible, les enregistrements de journaux sont mis en mémoire tampon (file d'attente par défaut : 2048) et les enregistrements les plus anciens sont supprimés une fois la file pleine. Le processus continue sans bloquer le service. Configurez un collecteur OTel local si vous avez besoin d'une mise en mémoire tampon sans perte pendant les pannes.

Les journaux sont également exportés sous le transport stdio, ce qui facilite la centralisation des journaux depuis les instances locales mcp-grafana invoquées par les clients IDE.

Exemple Docker avec métriques, tracing et journaux :

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

Application des requêtes Loki

--loki-enforced-matchers permet à un opérateur de restreindre les flux de journaux Loki que le serveur peut jamais lire, en appliquant un ET logique d'un ensemble fixe de correspondants d'étiquettes LogQL à chaque requête native-Loki que le serveur émet. Cela est utile lorsqu'une source de données contient des flux qui ne doivent pas être exposés (par exemple, des journaux pouvant contenir des informations sensibles) mais que vous ne pouvez pas restreindre l'accès au niveau de Grafana ou Loki (OSS n'a pas de contrôle d'accès par étiquette par source de données ou par utilisateur).

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

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

Comment cela fonctionne :

Les correspondants sont analysés une fois au démarrage (une entrée invalide interrompt le serveur) et ajoutés à chaque sélecteur de flux dans chaque requête. Parce que Loki applique un ET logique des correspondants dans un sélecteur, une requête utilisateur ne peut jamais que réduire les résultats dans les limites appliquées — elle ne peut jamais les élargir. Un sélecteur utilisateur en conflit avec la politique (par exemple, demander {namespace="vault"} sous une exclusion) ne renvoie simplement rien.
Cela couvre query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names et list_loki_label_values.
Cela échoue fermé : toute requête qui ne peut pas être analysée est rejetée plutôt qu'envoyée non filtrée.
Les sources de données VictoriaLogs utilisent LogsQL, qui ne peut pas être réécrit en toute sécurité, donc elles sont refusées entièrement pendant que l'application est activée.
Les correspondants purement négatifs ne peuvent pas limiter les points de terminaison d'énumération d'étiquettes (Loki rejette un sélecteur autonome sans correspondant positif). Contrôlez ce cas limite avec --loki-label-enumeration-fallback (reject par défaut, ou unfiltered pour permettre l'énumération non limitée des métadonnées d'étiquettes — les lignes de journaux ne sont jamais exposées). Les correspondants positifs/de liste blanche ne sont pas affectés.

[!IMPORTANT] L'application ne s'applique qu'aux outils de requête Loki. D'autres outils peuvent atteindre les données de journaux Loki par des chemins qui ne touchent jamais le backend appliqué, donc pour que la restriction tienne réellement, vous devez également les désactiver :

--disable-api — grafana_api_request peut interroger le proxy de source de données Loki directement (contournement complet).

--disable-rendering — get_panel_image rend les panneaux Loki côté serveur, produisant des images avec des lignes de journaux non restreintes.

--disable-sift — Les investigations Sift analysent les journaux Loki côté serveur sur tous les flux.

--disable-assistant — ask_assistant délègue à Grafana Assistant, qui lit Loki côté serveur sur tous les flux. Uniquement enregistré lorsque les outils d'écriture sont activés, donc --disable-write le ferme également.

Le serveur journalise un avertissement au démarrage nommant chacun de ceux qui sont encore activés. run_panel_query est sûr (il réutilise le chemin de requête appliqué). Les outils Tempo interrogent les traces, pas les journaux Loki, donc ils ne sont pas un contournement. Les instantanés de tableaux de bord (--disable-snapshot) peuvent également intégrer des données de panneaux de journaux capturées en dehors de l'application.

Dépannage

Compatibilité des versions Grafana

Si vous rencontrez l'erreur suivante lors de l'utilisation d'outils liés aux sources de données :

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

Cela indique généralement que vous utilisez une version de Grafana antérieure à 9.0. Le point de terminaison d'API /datasources/uid/{uid} a été introduit dans Grafana 9.0, et les opérations de source de données échoueront sur les versions antérieures.

Solution : Mettez à niveau votre instance Grafana vers la version 9.0 ou ultérieure pour résoudre ce problème.

Développement

Les contributions sont les bienvenues ! Veuillez lire CONTRIBUTING.md d'abord — il couvre ce qui appartient à ce serveur et comment le proposer. Si vous ajoutez un nouvel outil, veuillez ouvrir une proposition d'outil avant d'écrire le code. Chaque outil activé par défaut est envoyé au modèle à chaque requête par chaque utilisateur, nous préférons donc discuter de l'idée plutôt que de refuser une pull request terminée. Les corrections de bugs, la documentation, les tests et les nouveaux paramètres sur les outils existants ne nécessitent pas de proposition — envoyez simplement une PR.

Ce projet est écrit en Go. Installez Go en suivant les instructions pour votre plateforme.

Pour exécuter le serveur localement en mode STDIO (qui est le mode par défaut pour le développement local), utilisez :

make run

Pour exécuter le serveur localement en mode SSE, utilisez :

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

Vous pouvez également exécuter le serveur en utilisant le transport SSE dans une image Docker personnalisée. Tout comme l'image Docker publiée, le point d'entrée de cette image personnalisée est par défaut en mode SSE. Pour construire l'image, utilisez :

make build-image

Et pour exécuter l'image en mode SSE (le mode par défaut), utilisez :

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

Si vous devez l'exécuter en mode STDIO à la place, remplacez le paramètre de transport :

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

Tests

Il existe trois types de tests disponibles :

Tests unitaires (aucune dépendance externe requise) :

make test-unit

Vous pouvez également exécuter les tests unitaires avec :

make test

Tests d'intégration (nécessite que les conteneurs docker soient démarrés) :

make test-integration

Tests cloud (nécessite une instance Grafana cloud et des identifiants) :

make test-cloud

Remarque : Les tests cloud sont automatiquement configurés dans l'intégration continue. Pour le développement local, vous devrez configurer votre propre instance Grafana Cloud et vos identifiants.

Des tests d'intégration plus complets nécessiteront qu'une instance Grafana soit exécutée localement sur le port 3000 ; vous pouvez en démarrer une avec Docker Compose :

docker-compose up -d

Les tests d'intégration peuvent être exécutés avec :

make test-all

Si vous ajoutez d'autres outils, veuillez ajouter des tests d'intégration pour ceux-ci. Les tests existants devraient constituer un bon point de départ.

Linting

Pour linter le code, exécutez :

make lint

Cela inclut un linter personnalisé qui vérifie les virgules non échappées dans les balises de structure jsonschema. Les virgules dans les champs description doivent être échappées avec \\, pour éviter une troncature silencieuse. Vous pouvez exécuter uniquement ce linter avec :

make lint-jsonschema

Consultez la documentation du linter JSONSchema pour plus de détails.

Licence

Ce projet est sous licence Apache License, Version 2.0.