Grafana MCP Server

oficial

Busca paneles, investiga incidentes y consulta fuentes de datos en tu instancia de Grafana.

GitHub
3.2k

Documentación

Servidor MCP de Grafana

Unit Tests Integration Tests E2E Tests Go Reference MCP Catalog

Un servidor de Protocolo de Contexto de Modelo (MCP) para Grafana.

Esto proporciona acceso a tu instancia de Grafana y al ecosistema que la rodea.

Inicio Rápido

Requiere uv. Añade lo siguiente a la configuración de tu cliente MCP (por ejemplo, Claude Desktop, Cursor):

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

Para Grafana Cloud, reemplaza GRAFANA_URL con la URL de tu instancia (por ejemplo, https://myinstance.grafana.net). Consulta Uso para más opciones de instalación, incluyendo Docker, binario y Helm.

Requisitos

  • Se requiere Grafana versión 9.0 o posterior para una funcionalidad completa. Algunas características, particularmente las operaciones relacionadas con fuentes de datos, pueden no funcionar correctamente con versiones anteriores debido a la falta de endpoints de API.

Características

Las siguientes características están actualmente disponibles en el servidor MCP. Esta lista es solo para fines informativos y no representa una hoja de ruta ni un compromiso de características futuras.

Paneles

  • Buscar paneles: Encuentra paneles por título u otros metadatos.
  • Obtener panel por UID: Recupera los detalles completos del panel usando su identificador único. Advertencia: Los paneles grandes pueden consumir un espacio significativo en la ventana de contexto.
  • Obtener resumen del panel: Obtén una visión general compacta de un panel que incluye título, número de paneles, tipos de paneles, variables y metadatos sin el JSON completo para minimizar el uso de la ventana de contexto.
  • Obtener propiedad del panel: Extrae partes específicas de un panel usando expresiones JSONPath (por ejemplo, $.title, $.panels[*].title) para obtener solo los datos necesarios y reducir el consumo de la ventana de contexto.
  • Actualizar o crear un panel: Modifica paneles existentes o crea nuevos. Advertencia: Requiere el JSON completo del panel, lo que puede consumir grandes cantidades de espacio en la ventana de contexto.
  • Parchear panel: Aplica cambios específicos a un panel sin requerir el JSON completo, reduciendo significativamente el uso de la ventana de contexto para modificaciones dirigidas.
  • Obtener consultas de panel e información de fuente de datos: Obtén el título, la cadena de consulta y la información de la fuente de datos (incluyendo UID y tipo, si están disponibles) de cada panel en un tablero.

Ejecutar Consulta de Panel

Nota: Las herramientas de ejecución de consulta de panel están deshabilitadas por defecto. Para habilitarlas, añade runpanelquery a tu bandera --enabled-tools.

  • Ejecutar consulta de panel: Ejecuta la consulta de un panel de tablero con rangos de tiempo personalizados y anulaciones de variables.

Gestión de la Ventana de Contexto

Las herramientas de paneles ahora incluyen varias estrategias para gestionar el uso de la ventana de contexto de manera efectiva (issue #101):

  • Usa get_dashboard_summary para obtener una visión general del panel y planificar modificaciones.
  • Usa get_dashboard_property con JSONPath cuando solo necesites partes específicas del panel.
  • Evita get_dashboard_by_uid a menos que necesites específicamente el JSON completo del panel.

Fuentes de Datos

  • Listar y obtener información de fuentes de datos: Visualiza todas las fuentes de datos configuradas y recupera información detallada sobre cada una.
    • Tipos de fuentes de datos soportados: Prometheus, Loki, ClickHouse, CloudWatch, Elasticsearch, OpenSearch, Snowflake, Athena.

Ejemplos de Consultas

Nota: Las herramientas de ejemplos de consultas están deshabilitadas por defecto. Para habilitarlas, añade examples a tu bandera --enabled-tools.

  • Obtener ejemplos de consultas: Recupera consultas de ejemplo para diferentes tipos de fuentes de datos para aprender la sintaxis de consulta.

Consultas a Prometheus

  • Consultar Prometheus: Ejecuta consultas PromQL (soporta tanto consultas de métricas instantáneas como de rango) contra fuentes de datos Prometheus.
  • Consultar metadatos de Prometheus: Recupera metadatos de métricas, nombres de métricas, nombres de etiquetas y valores de etiquetas de fuentes de datos Prometheus.
  • Consultar percentiles de histograma: Calcula valores de percentiles de histograma (p50, p90, p95, p99) usando histogram_quantile.

Consultas a Loki

  • Consultar logs y métricas de Loki: Ejecuta tanto consultas de log como consultas de métricas usando LogQL contra fuentes de datos Loki.
  • Consultar metadatos de Loki: Recupera nombres de etiquetas, valores de etiquetas y estadísticas de flujo de fuentes de datos Loki.
  • Consultar patrones de Loki: Recupera patrones de log detectados por Loki para identificar estructuras de log comunes y anomalías.

Consultas a InfluxDB

Nota: Las herramientas de InfluxDB están deshabilitadas por defecto. Para habilitarlas, añade influxdb a tu bandera --enabled-tools.

  • Consultar InfluxDB: Ejecuta consultas contra fuentes de datos InfluxDB usando InfluxQL (v1.x) o Flux (v2.x). El dialecto se infiere de la configuración de la fuente de datos, o se puede establecer explícitamente mediante el parámetro dialect.

Consultas a ClickHouse

Nota: Las herramientas de ClickHouse están deshabilitadas por defecto. Para habilitarlas, añade clickhouse a tu bandera --enabled-tools.

  • Listar tablas de ClickHouse: Lista todas las tablas en una base de datos ClickHouse con conteo de filas y tamaños.
  • Describir esquema de tabla: Obtén nombres de columnas, tipos y metadatos para una tabla de ClickHouse.
  • Consultar ClickHouse: Ejecuta consultas SQL con soporte para sustitución de macros y variables de Grafana.

Consultas a CloudWatch

Nota: Las herramientas de CloudWatch están deshabilitadas por defecto. Para habilitarlas, añade cloudwatch a tu bandera --enabled-tools.

  • Listar espacios de nombres de CloudWatch: Descubre los espacios de nombres de AWS CloudWatch disponibles.
  • Listar métricas de CloudWatch: Lista las métricas disponibles en un espacio de nombres específico.
  • Listar dimensiones de CloudWatch: Obtén dimensiones para filtrar consultas de métricas.
  • Consultar CloudWatch: Ejecuta consultas de métricas de CloudWatch con soporte para rango de tiempo.

Consultas a Graphite

Nota: Las herramientas de Graphite están deshabilitadas por defecto. Para habilitarlas, añade graphite a tu bandera --enabled-tools.

  • Consultar Graphite: Ejecuta consultas de la API de renderizado de Graphite contra una fuente de datos Graphite.
  • Listar métricas de Graphite: Navega y descubre rutas de métricas de Graphite.
  • Listar etiquetas de Graphite: Lista las etiquetas de Graphite disponibles y sus valores.
  • Consultar densidad de Graphite: Consulta la densidad de métricas de Graphite para un patrón dado.

Consultas a Athena

Nota: Las herramientas de Athena están deshabilitadas por defecto. Para habilitarlas, añade athena a tu bandera --enabled-tools.

  • Listar catálogos de Athena: Descubre los catálogos de datos disponibles (por ejemplo, AwsDataCatalog, conectores Iceberg).
  • Listar bases de datos de Athena: Lista las bases de datos en un catálogo de Athena.
  • Listar tablas de Athena: Lista las tablas en una base de datos de Athena.
  • Describir tabla de Athena: Obtén los nombres de las columnas de una tabla de Athena.
  • Consultar Athena: Ejecuta consultas SQL contra Amazon Athena a través de Grafana con sustitución de macros, aplicación de límites y soporte para variables de plantilla.

Consultas a Snowflake

Nota: Las herramientas de Snowflake están deshabilitadas por defecto. Para habilitarlas, añade snowflake a tu bandera --enabled-tools.

Las consultas pasan por la fuente de datos Snowflake de Grafana (plugin Grafana Enterprise grafana-snowflake-datasource), por lo que la autenticación es manejada por la configuración de la fuente de datos en Grafana — las credenciales nunca son vistas por el servidor MCP. Este es el mismo modelo utilizado para las herramientas de ClickHouse.

  • Listar tablas de Snowflake: Descubre tablas (con base de datos, esquema, tipo, conteo de filas y tamaño) a través de INFORMATION_SCHEMA.TABLES. Filtros opcionales de base de datos/esquema.
  • Describir esquema de tabla: Obtén nombres de columnas, tipos de datos, nulabilidad, valores predeterminados y comentarios para una tabla de Snowflake.
  • Consultar Snowflake: Ejecuta consultas SQL con soporte para sustitución de macros y variables. Útil para consultar tablas de eventos de Snowflake (por ejemplo, SNOWFLAKE.TELEMETRY.EVENTS) para logs y trazas, o cualquier tabla de usuario.
    • Macros soportados: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (Unix ms), $__interval (segundos), $__interval_ms, y ${varname} para sustitución de variables de plantilla.

Consultas a Elasticsearch/OpenSearch

Nota: Las herramientas de Elasticsearch/OpenSearch están deshabilitadas por defecto. Para habilitarlas, añade elasticsearch a tu bandera --enabled-tools.

  • Consultar Elasticsearch/OpenSearch: Ejecuta consultas de búsqueda contra fuentes de datos Elasticsearch u OpenSearch usando sintaxis de consulta Lucene o Elasticsearch Query DSL. Soporta filtrado por rango de tiempo y recuperación de logs, métricas o cualquier dato indexado. Devuelve documentos con su índice, ID, campos de origen y puntuación de relevancia opcional.

Consultas a Quickwit

Nota: Las herramientas de Quickwit están deshabilitadas por defecto. Para habilitarlas, añade quickwit a tu bandera --enabled-tools.

  • Consultar Quickwit: Ejecuta consultas de búsqueda contra fuentes de datos Quickwit usando sintaxis de consulta Lucene o Query DSL parcial compatible con Elasticsearch. Soporta filtrado por rango de tiempo y recuperación de logs u otros documentos indexados. Devuelve documentos con su índice, ID, campos de origen y puntuación de relevancia opcional.

Incidentes

  • Buscar, crear y actualizar incidentes: Gestiona incidentes en Grafana Incident, incluyendo búsqueda, creación y adición de actividades a incidentes.

Investigaciones de Sift

  • Listar investigaciones de Sift: Recupera una lista de investigaciones de Sift, con soporte para un parámetro de límite.
  • Obtener investigación de Sift: Recupera detalles de una investigación de Sift específica por su UUID.
  • Obtener análisis de Sift: Recupera un análisis específico de una investigación de Sift.
  • Encontrar patrones de error en logs: Detecta patrones de error elevados en logs de Loki usando Sift.
  • Encontrar solicitudes lentas: Detecta solicitudes lentas usando Sift (Tempo).

Alertas

  • Listar y obtener información de reglas de alerta: Visualiza las reglas de alerta y sus estados (activa/normal/error/etc.) en Grafana. Soporta tanto reglas gestionadas por Grafana como reglas gestionadas por fuentes de datos de Prometheus o Loki.
  • Crear y actualizar reglas de alerta: Crea nuevas reglas de alerta o modifica las existentes.
  • Eliminar reglas de alerta: Elimina reglas de alerta por UID.
  • Gestionar enrutamiento de alertas: Visualiza políticas de notificación, puntos de contacto e intervalos de tiempo. Soporta tanto puntos de contacto gestionados por Grafana como receptores de fuentes de datos externas de Alertmanager (Prometheus Alertmanager, Mimir, Cortex).

Grafana OnCall

  • Listar y gestionar horarios: Visualiza y gestiona los horarios de guardia en Grafana OnCall.
  • Obtener detalles de turno: Recupera información detallada sobre turnos de guardia específicos.
  • Obtener usuarios actualmente de guardia: Ve qué usuarios están actualmente de guardia para un horario.
  • Listar equipos y usuarios: Visualiza todos los equipos y usuarios de OnCall.
  • Listar grupos de alertas: Visualiza y filtra grupos de alertas de Grafana OnCall por varios criterios, incluyendo estado, integración, etiquetas y rango de tiempo.
  • Obtener detalles de grupo de alertas: Recupera información detallada sobre un grupo de alertas específico por su ID.

Administración

Nota: Las herramientas de administración están deshabilitadas por defecto. Para habilitarlas, incluye admin en tu bandera --enabled-tools.

  • Listar equipos: Visualiza todos los equipos configurados en Grafana.
  • Listar usuarios: Visualiza todos los usuarios en una organización en Grafana.
  • Listar todos los roles: Lista todos los roles de Grafana, con un filtro opcional para roles delegables.
  • Obtener detalles de rol: Obtén detalles de un rol de Grafana específico por UID.
  • Listar asignaciones para un rol: Lista todos los usuarios, equipos y cuentas de servicio asignados a un rol.
  • Listar roles para usuarios: Lista todos los roles asignados a uno o más usuarios.
  • Listar roles para equipos: Lista todos los roles asignados a uno o más equipos.
  • Listar permisos para un recurso: Lista todos los permisos definidos para un recurso específico (panel, fuente de datos, carpeta, etc.).
  • Describir un recurso de Grafana: Lista los permisos disponibles y las capacidades de asignación para un tipo de recurso.

Navegación

  • Generar enlaces profundos: Cree URLs de enlace profundo precisas para recursos de Grafana en lugar de depender de la adivinación de URLs por parte del LLM.
    • Enlaces a paneles: Genere enlaces directos a paneles usando su UID (ej., http://localhost:3000/d/dashboard-uid)
    • Enlaces a paneles específicos: Cree enlaces a paneles concretos dentro de los dashboards con el parámetro viewPanel (ej., http://localhost:3000/d/dashboard-uid?viewPanel=5)
    • Enlaces a Explore: Genere enlaces a Grafana Explore con fuentes de datos preconfiguradas (ej., http://localhost:3000/explore?left={"datasource":"prometheus-uid"})
    • Soporte de rango de tiempo: Añada parámetros de rango de tiempo a los enlaces (from=now-1h&to=now)
    • Parámetros personalizados: Incluya parámetros de consulta adicionales como variables de dashboard o intervalos de actualización

Anotaciones

  • Obtener Anotaciones: Consulte anotaciones con filtros. Soporta rango de tiempo, UID de dashboard, etiquetas y modo de coincidencia.
  • Crear Anotación: Cree una nueva anotación en un dashboard o panel.
  • Crear Anotación Graphite: Cree anotaciones usando el formato Graphite (what, when, tags, data).
  • Actualizar Anotación: Reemplace todos los campos de una anotación existente (actualización completa).
  • Parchear Anotación: Actualice solo campos específicos de una anotación (actualización parcial).
  • Obtener Etiquetas de Anotación: Liste las etiquetas de anotación disponibles con filtrado opcional.

Instantáneas

  • Listar instantáneas: Liste las instantáneas de dashboard con filtros opcionales de consulta y límite.
  • Obtener instantánea: Recupere los metadatos de la instantánea y la carga útil del dashboard por clave de instantánea.
  • Crear instantánea: Cree una instantánea de dashboard a partir de una carga útil completa del dashboard, con opciones de expiración y de instantánea externa.
  • Eliminar instantánea: Elimine una instantánea por su clave.

Renderizado

  • Obtener imagen de panel o dashboard: Renderice un panel de dashboard de Grafana o un dashboard completo como una imagen PNG. Devuelve la imagen como datos codificados en base64 para usar en informes, alertas o presentaciones. Soporta la personalización de dimensiones, rango de tiempo, tema, escala y variables de dashboard. También soporta el renderizado de dashboards aún no aplicados desde una rama de repositorio de aprovisionamiento (ej., una vista previa de PR de git-sync) mediante el parámetro opcional provisioningPreview.

Aprovisionamiento

  • Listar repositorios de aprovisionamiento: Liste los repositorios de aprovisionamiento configurados para esta instancia de Grafana (ej., fuentes de git-sync), devolviendo el slug de cada repositorio junto con su URL de origen, rama, ruta, estado de sincronización y salud.
  • Validar archivo de aprovisionamiento: Simule la aplicación de un archivo de un repositorio de aprovisionamiento en una rama o commit determinados. Devuelve si sería aceptado, la acción sobre el recurso (crear/actualizar), el tipo de recurso objetivo y cualquier error de validación estructurado — la misma superficie de admisión que usa el comentarista de PR de Grafana.

La lista de herramientas es configurable, por lo que puede elegir qué herramientas quiere poner a disposición del cliente MCP. Esto es útil si no utiliza cierta funcionalidad o si no quiere ocupar demasiado la ventana de contexto. Para deshabilitar una categoría de herramientas, use la bandera --disable-<category> al iniciar el servidor. Por ejemplo, para deshabilitar las herramientas de OnCall, use --disable-oncall, o para deshabilitar la generación de enlaces profundos de navegación, use --disable-navigation.

Permisos RBAC

Cada herramienta requiere permisos RBAC específicos para funcionar correctamente. Al crear una cuenta de servicio para el servidor MCP, asegúrese de que tenga los permisos necesarios según las herramientas que planee usar. Los permisos listados son las acciones mínimas requeridas; también puede necesitar los ámbitos apropiados (ej., datasources:*, dashboards:*, folders:*) dependiendo de su caso de uso.

Consejo: Si no está familiarizado con RBAC de Grafana o quiere una configuración más rápida y sencilla en lugar de configurar muchos ámbitos granulares, puede asignar un rol integrado como Editor a la cuenta de servicio. El rol Editor otorga acceso amplio de lectura/escritura que permitirá la mayoría de las operaciones del servidor MCP; es menos granular (y por lo tanto menos restrictivo) que los ámbitos aplicados manualmente, así que úselo solo cuando la conveniencia sea más importante que el acceso estricto con privilegios mínimos.

Nota: Las herramientas de Grafana Incident y Sift usan roles básicos de Grafana en lugar de permisos RBAC detallados:

  • Rol de Visualizador: Requerido para operaciones de solo lectura (listar incidentes, obtener investigaciones)
  • Rol de Editor: Requerido para operaciones de escritura (crear incidentes, modificar investigaciones)

Para más información sobre RBAC de Grafana, consulte la documentación oficial.

Ámbitos RBAC

Los ámbitos definen los recursos específicos a los que se aplican los permisos. Cada acción requiere la combinación adecuada de permiso y ámbito.

Patrones de ámbito comunes:

  • Acceso amplio: Use comodines * para acceso a nivel de organización

    • datasources:* - Acceso a todas las fuentes de datos
    • dashboards:* - Acceso a todos los dashboards
    • folders:* - Acceso a todas las carpetas
    • teams:* - Acceso a todos los equipos

  • Acceso limitado: Use UIDs o IDs específicos para restringir el acceso a recursos individuales

    • datasources:uid:prometheus-uid - Acceso solo a una fuente de datos Prometheus específica
    • dashboards:uid:abc123 - Acceso solo al dashboard con UID abc123
    • folders:uid:xyz789 - Acceso solo a la carpeta con UID xyz789
    • teams:id:5 - Acceso solo al equipo con ID 5
    • global.users:id:123 - Acceso solo al usuario con ID 123

Ejemplos:

  • Acceso completo al servidor MCP: Otorgue permisos amplios para todas las herramientas

    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)

  • Acceso limitado a fuentes de datos: Solo consulte instancias específicas de Prometheus y Loki

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

  • Acceso específico a dashboards: Solo lectura de dashboards específicos

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

Herramientas

HerramientaCategoríaDescripciónPermisos RBAC requeridosÁmbitos requeridos
list_teamsAdminListar todos los equiposteams:readteams:* o teams:id:1
list_users_by_orgAdminListar todos los usuarios de una organizaciónusers:readglobal.users:* o global.users:id:123
list_all_rolesAdminListar todos los roles de Grafanaroles:readroles:*
get_role_detailsAdminObtener detalles de un rol de Grafanaroles:readroles:uid:editor
get_role_assignmentsAdminListar asignaciones de un rolroles:readroles:uid:editor
list_user_rolesAdminListar roles de usuariosroles:readglobal.users:id:123
list_team_rolesAdminListar roles de equiposroles:readteams:id:7
get_resource_permissionsAdminListar permisos de un recursopermissions:readdashboards:uid:abcd1234
get_resource_descriptionAdminDescribir un tipo de recurso de Grafanapermissions:readdashboards:*
search_dashboardsBúsquedaBuscar panelesdashboards:readdashboards:* o dashboards:uid:abc123
get_dashboard_by_uidPanelObtener un panel por uiddashboards:readdashboards:uid:abc123
update_dashboardPanelActualizar o crear un nuevo paneldashboards:create, dashboards:writedashboards:*, folders:* o folders:uid:xyz789
get_dashboard_panel_queriesPanelObtener título del panel, consultas, UID y tipo de la fuente de datos de un paneldashboards:readdashboards:uid:abc123
run_panel_queryRunPanelQuery*Ejecutar una o más consultas de paneldashboards:read, datasources:querydashboards:uid:*, datasources:uid:*
get_dashboard_propertyPanelExtraer partes específicas de un panel usando expresiones JSONPathdashboards:readdashboards:uid:abc123
get_dashboard_summaryPanelObtener un resumen compacto de un panel sin el JSON completodashboards:readdashboards:uid:abc123
list_datasourcesFuentes de datosListar fuentes de datosdatasources:readdatasources:*
get_datasourceFuentes de datosObtener una fuente de datos por UID o nombredatasources:readdatasources:uid:prometheus-uid
get_query_examplesEjemplos*Obtener consultas de ejemplo para un tipo de fuente de datosdatasources:readdatasources:*
query_prometheusPrometheusEjecutar una consulta contra una fuente de datos de Prometheusdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_metadataPrometheusListar metadatos de métricasdatasources:querydatasources:uid:prometheus-uid
list_prometheus_metric_namesPrometheusListar nombres de métricas disponiblesdatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_namesPrometheusListar nombres de etiquetas que coinciden con un selectordatasources:querydatasources:uid:prometheus-uid
list_prometheus_label_valuesPrometheusListar valores para una etiqueta específicadatasources:querydatasources:uid:prometheus-uid
query_prometheus_histogramPrometheusCalcular valores de percentiles de histogramadatasources:querydatasources:uid:prometheus-uid
list_incidentsIncidenteListar incidentes en Grafana IncidentRol de visualizadorN/D
create_incidentIncidenteCrear un incidente en Grafana IncidentRol de editorN/D
add_activity_to_incidentIncidenteAñadir un elemento de actividad a un incidente en Grafana IncidentRol de editorN/D
get_incidentIncidenteObtener un único incidente por IDRol de visualizadorN/D
query_loki_logsLokiConsultar y recuperar registros usando LogQL (consultas de registro o métricas)datasources:querydatasources:uid:loki-uid
list_loki_label_namesLokiListar todos los nombres de etiquetas disponibles en los registrosdatasources:querydatasources:uid:loki-uid
list_loki_label_valuesLokiListar valores para una etiqueta de registro específicadatasources:querydatasources:uid:loki-uid
query_loki_statsLokiObtener estadísticas sobre flujos de registrosdatasources:querydatasources:uid:loki-uid
query_loki_patternsLokiConsultar patrones de registro detectados para identificar estructuras comunesdatasources:querydatasources:uid:loki-uid
analyze_loki_labelsLokiAuditar una estrategia de etiquetas de Loki (en vivo o estática) y opcionalmente diagnosticar el rendimiento de consultasdatasources:querydatasources:uid:loki-uid
suggest_loki_alloy_label_configConfiguraciónGenerar un fragmento de loki.process de Alloy que imponga etiquetas aprobadasN/DN/D
query_influxdbInfluxDBConsultar InfluxDB usando InfluxQL (v1) o Flux (v2)datasources:querydatasources:uid:influxdb-uid
list_clickhouse_tablesClickHouse*Listar tablas en una base de datos ClickHousedatasources:querydatasources:uid:*
describe_clickhouse_tableClickHouse*Obtener esquema de tabla con tipos de columnadatasources:querydatasources:uid:*
query_clickhouseClickHouse*Ejecutar consultas SQL con sustitución de macrosdatasources:querydatasources:uid:*
list_cloudwatch_namespacesCloudWatch*Listar espacios de nombres de AWS CloudWatch disponiblesdatasources:querydatasources:uid:*
list_cloudwatch_dimensionsCloudWatch*Listar dimensiones para una métricadatasources:querydatasources:uid:*
query_cloudwatchCloudWatch*Ejecutar consultas de métricas de CloudWatchdatasources:querydatasources:uid:*
list_athena_catalogsAthena*Listar catálogos de datos de Athena disponiblesdatasources:querydatasources:uid:*
list_athena_databasesAthena*Listar bases de datos en un catálogo de Athenadatasources:querydatasources:uid:*
list_athena_tablesAthena*Listar tablas en una base de datos de Athenadatasources:querydatasources:uid:*
describe_athena_tableAthena*Obtener nombres de columnas para una tabla de Athenadatasources:querydatasources:uid:*
query_athenaAthena*Ejecutar consultas SQL con sustitución de macrosdatasources:querydatasources:uid:*
query_elasticsearchElasticsearch/OpenSearch*Consultar Elasticsearch u OpenSearch usando sintaxis Lucene o Query DSLdatasources:querydatasources:uid:datasource-uid
query_quickwitQuickwit*Consultar Quickwit usando sintaxis Lucene o Query DSLdatasources:querydatasources:uid:quickwit-uid
list_snowflake_tablesSnowflake*Listar tablas en una base de datos/esquema de Snowflake mediante INFORMATION_SCHEMAdatasources:querydatasources:uid:*
describe_snowflake_tableSnowflake*Obtener esquema de tabla (tipos de columna, nulabilidad, valores predeterminados, comentarios)datasources:querydatasources:uid:*
query_snowflakeSnowflake*Ejecutar consultas SQL con sustitución de macros/variablesdatasources:querydatasources:uid:*
alerting_manage_rulesAlertasGestionar reglas de alerta (listar, obtener, versiones, crear, actualizar, eliminar)alert.rules:read + alert.rules:write para mutacionesfolders:* o folders:uid:alerts-folder
alerting_manage_routingAlertasGestionar políticas de notificación, puntos de contacto e intervalos de tiempoalert.notifications:readÁmbito global
list_oncall_schedulesOnCallListar horarios de Grafana OnCallgrafana-oncall-app.schedules:readÁmbitos específicos del plugin
get_oncall_shiftOnCallObtener detalles de un turno específico de OnCallgrafana-oncall-app.schedules:readÁmbitos específicos del plugin
get_current_oncall_usersOnCallObtener usuarios actualmente de guardia para un horario específicografana-oncall-app.schedules:readÁmbitos específicos del plugin
list_oncall_teamsOnCallListar equipos de Grafana OnCallgrafana-oncall-app.user-settings:readÁmbitos específicos del plugin
list_oncall_usersOnCallListar usuarios de Grafana OnCallgrafana-oncall-app.user-settings:readÁmbitos específicos del plugin
list_alert_groupsOnCallListar grupos de alertas de Grafana OnCall con opciones de filtradografana-oncall-app.alert-groups:readÁmbitos específicos del plugin
get_alert_groupOnCallObtener un grupo de alertas específico de Grafana OnCall por su IDgrafana-oncall-app.alert-groups:readÁmbitos específicos del plugin
get_sift_investigationSiftRecuperar una investigación existente de Sift por su UUIDRol de visualizadorN/A
get_sift_analysisSiftRecuperar un análisis específico de una investigación de SiftRol de visualizadorN/A
list_sift_investigationsSiftRecuperar una lista de investigaciones de Sift con un límite opcionalRol de visualizadorN/A
find_error_pattern_logsSiftEncuentra patrones de error elevados en los logs de Loki.Rol de editorN/A
find_slow_requestsSiftEncuentra solicitudes lentas de las fuentes de datos de tempo relevantes.Rol de editorN/A
list_pyroscope_label_namesPyroscopeListar nombres de etiquetas que coinciden con un selectordatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_label_valuesPyroscopeListar valores de etiquetas que coinciden con un selector para un nombre de etiquetadatasources:querydatasources:uid:pyroscope-uid
list_pyroscope_profile_typesPyroscopeListar tipos de perfil disponiblesdatasources:querydatasources:uid:pyroscope-uid
query_pyroscopePyroscopeConsultar perfiles, métricas o ambos desde Pyroscopedatasources:querydatasources:uid:pyroscope-uid
get_assertionsAssertsObtener resumen de aserciones para una entidad dadaPermisos específicos del pluginÁmbitos específicos del plugin
generate_deeplinkNavegaciónGenerar URLs de enlace profundo precisas para recursos de GrafanaNinguno (generación de URL de solo lectura)N/A
get_annotationsAnotacionesObtener anotaciones con filtrosannotations:readannotations:* o annotations:id:123
create_annotationAnotacionesCrear una nueva anotación (formato estándar o Graphite)annotations:writeannotations:*
update_annotationAnotacionesActualizar campos específicos de una anotación (actualización parcial)annotations:writeannotations:*
get_annotation_tagsAnotacionesListar etiquetas de anotación con filtrado opcionalannotations:readannotations:*
list_snapshotsInstantáneaListar instantáneas de panel con filtros opcionales de consulta y límitedashboards:readdashboards:* o dashboards:uid:abc123
get_snapshotInstantáneaObtener metadatos de instantánea y carga útil del panel por clave de instantáneadashboards:readdashboards:* o dashboards:uid:abc123
create_snapshotInstantáneaCrear una instantánea de panel a partir de una carga útil completa del paneldashboards:writedashboards:* o dashboards:uid:abc123
delete_snapshotInstantáneaEliminar una instantánea de panel por clave de instantáneadashboards:writedashboards:* o dashboards:uid:abc123
get_panel_imageRenderizadoRenderizar un panel o panel almacenado — o una vista previa de aprovisionamiento desde una rama de repositorio — como una imagen PNGdashboards:readdashboards:uid:abc123
list_provisioning_repositoriesAprovisionamientoListar repositorios de aprovisionamiento (ej. fuentes git-sync) con su URL de origen, rama, estado de sincronización y saludprovisioning.repositories:readN/A
validate_provisioning_fileAprovisionamientoAplicar en modo simulación un archivo de un repositorio de aprovisionamiento y reportar errores de validación de admisiónprovisioning.repositories:readN/A

Referencia de flags CLI

El binario mcp-grafana admite varios flags de línea de comandos para su configuración:

Opciones de transporte:

  • -t, --transport: Tipo de transporte (stdio, sse o streamable-http) - predeterminado: stdio
  • --address: Host y puerto para el servidor SSE/streamable-http - predeterminado: localhost:8000
  • --base-path: Ruta base para el servidor SSE/streamable-http
  • --endpoint-path: Ruta del endpoint para el servidor streamable-http - predeterminado: /

Depuración y registro:

  • --debug: Habilitar modo de depuración para registro detallado de peticiones/respuestas HTTP
  • --log-level: Nivel de registro (debug, info, warn, error) - predeterminado: info

Observabilidad:

  • --metrics: Habilitar endpoint de métricas Prometheus en /metrics
  • --metrics-address: Dirección separada para el servidor de métricas (ej., :9090). Si está vacía, las métricas se sirven en el servidor principal
  • --slow-request-threshold: Registrar un evento cuando cualquier petición MCP (invocación de herramienta, listado, lectura de recurso, etc.) tarde más de esta duración. Acepta cadenas de duración de Go (ej., 500ms, 5s). El valor predeterminado 0 deshabilita el registro de peticiones lentas. Consulta la sección Registro de peticiones lentas.
  • --slow-request-log-level: Nivel de registro para eventos de peticiones lentas (info o warn) - predeterminado: warn.

Gestión de sesiones:

  • --session-idle-timeout-minutes: Tiempo de espera de inactividad de sesión en minutos. Las sesiones sin actividad durante este tiempo se eliminan automáticamente - predeterminado: 30. Establecer a 0 para deshabilitar la eliminación de sesiones. Solo relevante para transportes SSE y streamable-http.

Configuración de herramientas:

  • --enabled-tools: Lista separada por comas de categorías habilitadas - predeterminado: todas las categorías excepto admin, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery y snowflake. Para habilitar categorías deshabilitadas, añádelas a la lista (ej., "search,datasource,...,snowflake")
  • --max-loki-log-limit: Número máximo de líneas de log devueltas por llamada a query_loki_logs - predeterminado: 100. Nota: Establece esto al menos 1 por debajo del max_entries_limit_per_query del lado del servidor de Loki para permitir la detección de truncamiento (la herramienta solicita limit+1 internamente para detectar si existen más datos).
  • --disable-search: Deshabilitar herramientas de búsqueda
  • --disable-datasource: Deshabilitar herramientas de fuentes de datos
  • --disable-incident: Deshabilitar herramientas de incidencias
  • --disable-prometheus: Deshabilitar herramientas de prometheus
  • --disable-write: Deshabilitar herramientas de escritura (operaciones de creación/actualización)
  • --disable-loki: Deshabilitar herramientas de loki
  • --disable-elasticsearch: Deshabilitar herramientas de elasticsearch y opensearch
  • --disable-quickwit: Deshabilitar herramientas de quickwit
  • --disable-influxdb: Deshabilitar herramientas de InfluxDB
  • --disable-alerting: Deshabilitar herramientas de alertas
  • --disable-dashboard: Deshabilitar herramientas de dashboards
  • --disable-oncall: Deshabilitar herramientas de oncall
  • --disable-asserts: Deshabilitar herramientas de asserts
  • --disable-sift: Deshabilitar herramientas de sift
  • --disable-admin: Deshabilitar herramientas de administración
  • --disable-pyroscope: Deshabilitar herramientas de pyroscope
  • --disable-navigation: Deshabilitar herramientas de navegación
  • --disable-rendering: Deshabilitar herramientas de renderizado (exportación de imágenes de panel/dashboard)
  • --disable-snapshot: Deshabilitar herramientas de instantáneas
  • --disable-cloudwatch: Deshabilitar herramientas de CloudWatch
  • --disable-examples: Deshabilitar herramientas de ejemplos de consultas
  • --disable-clickhouse: Deshabilitar herramientas de ClickHouse
  • --disable-snowflake: Deshabilitar herramientas de Snowflake
  • --disable-runpanelquery: Deshabilitar herramientas de ejecución de consultas de panel
  • --disable-graphite: Deshabilitar herramientas de Graphite
  • --disable-athena: Deshabilitar herramientas de Athena
  • --disable-provisioning: Deshabilitar herramientas de aprovisionamiento

Modo de solo lectura

El flag --disable-write proporciona una forma de ejecutar el servidor MCP en modo de solo lectura, impidiendo cualquier operación de escritura en tu instancia de Grafana. Esto es útil para escenarios donde deseas proporcionar acceso seguro de solo lectura, como:

  • Usar cuentas de servicio con permisos limitados de solo lectura
  • Proporcionar a asistentes de IA datos de observabilidad sin capacidades de modificación
  • Ejecutar en entornos de producción donde el acceso de escritura debe estar restringido
  • Escenarios de prueba y desarrollo donde deseas prevenir modificaciones accidentales

Cuando --disable-write está habilitado, las siguientes operaciones de escritura se deshabilitan:

Herramientas de Dashboard:

  • update_dashboard

Herramientas de Carpeta:

  • create_folder

Herramientas de Incidencias:

  • create_incident
  • add_activity_to_incident

Herramientas de Alertas:

  • alerting_manage_rules (operaciones de crear, actualizar, eliminar)

Herramientas de Anotaciones:

  • create_annotation
  • update_annotation

Herramientas de Sift:

  • find_error_pattern_logs (crea investigaciones)
  • find_slow_requests (crea investigaciones)

Herramientas de Instantáneas:

  • create_snapshot
  • delete_snapshot

Todas las operaciones de lectura permanecen disponibles, permitiéndote consultar dashboards, ejecutar consultas PromQL/LogQL, listar recursos y recuperar datos.

Configuración TLS del cliente (para conexiones a Grafana):

  • --tls-cert-file: Ruta al archivo de certificado TLS para autenticación del cliente
  • --tls-key-file: Ruta al archivo de clave privada TLS para autenticación del cliente
  • --tls-ca-file: Ruta al archivo de certificado CA TLS para verificación del servidor
  • --tls-skip-verify: Omitir la verificación del certificado TLS (inseguro)

Configuración TLS del servidor (solo transporte streamable-http):

  • --server.tls-cert-file: Ruta al archivo de certificado TLS para HTTPS del servidor
  • --server.tls-key-file: Ruta al archivo de clave privada TLS para HTTPS del servidor

Uso

Este servidor MCP funciona tanto con instancias locales de Grafana como con Grafana Cloud. Para Grafana Cloud, usa la URL de tu instancia (ej., https://myinstance.grafana.net) en lugar de http://localhost:3000 en los ejemplos de configuración a continuación.

  1. Si usas autenticación por token de cuenta de servicio, crea una cuenta de servicio en Grafana con los permisos suficientes para usar las herramientas que desees, genera un token de cuenta de servicio y cópialo al portapapeles para usarlo en el archivo de configuración. Sigue la documentación de cuentas de servicio de Grafana para obtener detalles sobre la creación de tokens de cuenta de servicio. Consejo: Si no te sientes cómodo configurando ámbitos RBAC detallados, una opción más simple (pero menos restrictiva) es asignar el rol integrado Editor a la cuenta de servicio. Esto otorga acceso amplio de lectura/escritura que cubre la mayoría de las operaciones del servidor MCP — úsalo cuando la conveniencia supere los requisitos estrictos de privilegio mínimo.

    Nota: La variable de entorno GRAFANA_API_KEY está obsoleta y se eliminará en una versión futura. Por favor, migra a usar GRAFANA_SERVICE_ACCOUNT_TOKEN en su lugar. El nombre de variable antiguo seguirá funcionando por compatibilidad hacia atrás, pero mostrará advertencias de obsolescencia.

Leer el token de cuenta de servicio desde un archivo

En lugar de pasar el token en línea mediante GRAFANA_SERVICE_ACCOUNT_TOKEN, puedes apuntar GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE a una ruta de archivo que contenga el token. El archivo se lee de nuevo en cada petición, por lo que los tokens rotados se recogen automáticamente sin reiniciar el servidor.

Esto es particularmente útil en Kubernetes, donde un Secret montado como volumen se actualiza en el lugar cuando el Secret subyacente cambia (típicamente en ~1 minuto). Combinado con la caché de cliente por petición — que está indexada por el valor del token — un token rotado produce transparentemente un nuevo cliente sin reinicio del pod y sin tiempo de inactividad:

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

Los espacios en blanco circundantes (incluyendo un salto de línea final) se recortan del contenido del archivo. Si ambos GRAFANA_SERVICE_ACCOUNT_TOKEN y GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE están configurados, el token en línea tiene prioridad.

Soporte Multi-Organización

Puedes especificar con qué organización interactuar usando:

  • Variable de entorno: Establece GRAFANA_ORG_ID al ID numérico de la organización
  • Cabecera HTTP: Establece X-Grafana-Org-Id al usar transportes SSE o HTTP transmitible (la cabecera tiene prioridad sobre la variable de entorno - lo que significa que también puedes establecer una organización predeterminada).

Cuando se proporciona un ID de organización, el servidor MCP establecerá la cabecera X-Grafana-Org-Id en todas las peticiones a Grafana, asegurando que las operaciones se realicen dentro del contexto de la organización especificada.

Ejemplo con ID de organización:

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

Cabeceras HTTP personalizadas

Puedes añadir cabeceras HTTP arbitrarias a todas las peticiones a la API de Grafana usando la variable de entorno GRAFANA_EXTRA_HEADERS. El valor debe ser un objeto JSON que mapee nombres de cabecera a valores.

Ejemplo con cabeceras personalizadas:

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

Reenviar cabeceras desde el cliente (Solo SSE/Streamable-HTTP)

Cuando el servidor MCP se ejecuta detrás de una puerta de enlace o proxy inverso que maneja SSO (ej. un ALB de AWS con OIDC), la cookie de sesión de cada usuario debe llegar a Grafana para que pueda asociar la petición con el usuario autenticado. La variable de entorno GRAFANA_FORWARD_HEADERS habilita esto especificando una lista separada por comas de nombres de cabecera permitidos para copiar desde la petición HTTP entrante a cada petición saliente a la API de Grafana.

Esto solo aplica cuando se usan transportes SSE (-t sse) o streamable-http (-t streamable-http). No tiene efecto en modo stdio.

Ejemplo: reenviar la cookie de sesión

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

Puedes reenviar múltiples cabeceras separándolas con comas:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

Las cabeceras reenviadas se fusionan con cualquier cabecera definida en GRAFANA_EXTRA_HEADERS. Si un nombre de cabecera aparece en ambos, el valor de la petición entrante tiene prioridad para esa petición.

  1. Tienes varias opciones para instalar mcp-grafana:

    • uvx (recomendado): Si tienes uv instalado, no se necesita configuración adicional — uvx descargará y ejecutará automáticamente el servidor:

      uvx mcp-grafana

    • Imagen Docker: Usa la imagen Docker preconstruida de Docker Hub.

      Importante: El punto de entrada de la imagen Docker está configurado para ejecutar el servidor MCP en modo SSE por defecto, pero la mayoría de los usuarios querrán usar el modo STDIO para integración directa con asistentes de IA como Claude Desktop:

      1. Modo STDIO: Para el modo stdio debes sobrescribir explícitamente el valor predeterminado con -t stdio e incluir el flag -i para mantener stdin abierto:
      docker pull grafana/mcp-grafana
# For local Grafana:
docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
# For Grafana Cloud:
docker run --rm -i -e GRAFANA_URL=https://myinstance.grafana.net -e GRAFANA_SERVICE_ACCOUNT_TOKEN=<your service account token> grafana/mcp-grafana -t stdio
      1. Modo SSE: En este modo, el servidor se ejecuta como un servidor HTTP al que los clientes se conectan. Debes exponer el puerto 8000 usando el flag -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> grafana/mcp-grafana
      1. Modo HTTP Transmisible: En este modo, el servidor opera como un proceso independiente que puede manejar múltiples conexiones de cliente. Debes exponer el puerto 8000 usando el flag -p: Para este modo debes sobrescribir explícitamente el valor predeterminado con -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> grafana/mcp-grafana -t streamable-http

      Para modo HTTP transmisible HTTPS con certificados TLS de servidor:

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

    • Descargar binario: Descarga la última versión de mcp-grafana desde la página de releases y colócalo en tu $PATH.

    • Compilar desde el código fuente: Si tienes una cadena de herramientas Go instalada, también puedes compilarlo e instalarlo desde el código fuente, usando la variable de entorno GOBIN para especificar el directorio donde se debe instalar el binario. Esto también debería estar en tu $PATH.

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

    • Desplegar en Kubernetes usando Helm: usa el chart de Helm del repositorio de 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

  2. Añade la configuración del servidor a tu archivo de configuración de cliente. Por ejemplo, para Claude Desktop:

    Si usas uvx:

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

    Si usas el binario:

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

Nota: si ves Error: spawn mcp-grafana ENOENT en Claude Desktop, necesitas especificar la ruta completa a mcp-grafana.

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

Nota: El argumento -t stdio es esencial aquí porque sobrescribe el modo SSE predeterminado en la imagen Docker.

Usando VSCode con servidor MCP remoto

Si estás usando VSCode y ejecutando el servidor MCP en modo SSE (que es el predeterminado al usar la imagen Docker sin sobrescribir el transporte), asegúrate de que tu .vscode/settings.json incluya lo siguiente:

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

Para el modo HTTP transmitible por HTTPS con certificados TLS del servidor:

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

Modo de depuración

Puede habilitar el modo de depuración para el transporte de Grafana añadiendo el indicador -debug al comando. Esto proporcionará un registro detallado de las solicitudes y respuestas HTTP entre el servidor MCP y la API de Grafana, lo que puede ser útil para la resolución de problemas.

Para usar el modo de depuración con la configuración de Claude Desktop, actualice su configuración de la siguiente manera:

Si usa el binario:

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

Nota: Al igual que con la configuración estándar, el argumento -t stdio es necesario para anular el modo SSE predeterminado en la imagen de Docker.

Configuración TLS

Si su instancia de Grafana está detrás de mTLS o requiere certificados TLS personalizados, puede configurar el servidor MCP para usar certificados personalizados. El servidor admite las siguientes opciones de configuración TLS:

  • --tls-cert-file: Ruta al archivo de certificado TLS para autenticación del cliente
  • --tls-key-file: Ruta al archivo de clave privada TLS para autenticación del cliente
  • --tls-ca-file: Ruta al archivo de certificado CA TLS para verificación del servidor
  • --tls-skip-verify: Omitir la verificación del certificado TLS (inseguro, usar solo para pruebas)

Ejemplo con autenticación de certificado de cliente:

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

Ejemplo con 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 configuración TLS se aplica a todos los clientes HTTP utilizados por el servidor MCP, incluyendo:

  • El cliente principal de OpenAPI de Grafana
  • Clientes de fuentes de datos de Prometheus
  • Clientes de fuentes de datos de Loki
  • Clientes de gestión de incidencias
  • Clientes de investigación de Sift
  • Clientes de alertas
  • Clientes de Asserts

Ejemplos de uso directo de CLI:

Para pruebas con certificados autofirmados:

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

Con autenticación de certificado de cliente:

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

Solo con certificado CA personalizado:

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

Uso programático:

Si está usando esta biblioteca de forma programática, también puede crear funciones de contexto habilitadas para 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)

Validación de URL al conectar su propio servidor HTTP:

Cuando los consumidores de la biblioteca conectan las funciones de contexto de mcp-grafana en su propio http.Server, instale ValidateGrafanaURLMiddleware para rechazar cabeceras X-Grafana-URL mal formadas con 400 Bad Request (coincidiendo con el comportamiento del binario):

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

Al llamar a NewGrafanaClient directamente (stdio o construcción programática), valide previamente las URL no confiables para evitar un pánico alcanzable:

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

Ambos patrones comparten ValidateGrafanaURL como el validador único.

Configuración TLS del servidor (Solo transporte HTTP transmitible)

Al usar el transporte HTTP transmitible (-t streamable-http), puede configurar el servidor MCP para servir HTTPS en lugar de HTTP. Esto es útil cuando necesita asegurar la conexión entre su cliente MCP y el propio servidor.

El servidor admite las siguientes opciones de configuración TLS para el transporte HTTP transmitible:

  • --server.tls-cert-file: Ruta al archivo de certificado TLS para HTTPS del servidor (requerido para TLS)
  • --server.tls-key-file: Ruta al archivo de clave privada TLS para HTTPS del servidor (requerido para TLS)

Nota: Estos indicadores son completamente independientes de los indicadores TLS del cliente documentados anteriormente. Los indicadores TLS del cliente configuran cómo se conecta el servidor MCP a Grafana, mientras que estos indicadores TLS del servidor configuran cómo se conectan los clientes al servidor MCP cuando se usa el transporte HTTP transmitible.

Ejemplo con servidor HTTP transmitible HTTPS:

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

Esto iniciaría el servidor MCP en el puerto HTTPS 8443. Los clientes se conectarían entonces a https://localhost:8443/ en lugar de http://localhost:8000/.

Ejemplo de Docker con TLS del servidor:

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

Endpoint de verificación de estado

Al usar los transportes SSE (-t sse) o HTTP transmitible (-t streamable-http), el servidor MCP expone un endpoint de verificación de estado en /healthz. Este endpoint puede ser utilizado por balanceadores de carga, sistemas de monitoreo o plataformas de orquestación para verificar que el servidor está funcionando y aceptando conexiones.

Endpoint: GET /healthz

Respuesta:

  • Código de estado: 200 OK
  • Cuerpo: ok

Ejemplo de uso:

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

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

Nota: El endpoint de verificación de estado solo está disponible cuando se usan los transportes SSE o HTTP transmitible. No está disponible cuando se usa el transporte stdio (-t stdio), ya que stdio no expone un servidor HTTP.

Observabilidad

El servidor MCP admite métricas de Prometheus, rastreo distribuido de OpenTelemetry y exportación de registros de OpenTelemetry, siguiendo las convenciones semánticas de OTel MCP. El rastreo y la exportación de registros se configuran mediante variables de entorno estándar OTEL_* y funcionan con cualquier transporte.

Nota: mcp-grafana actualmente solo admite el transporte OTLP/gRPC tanto para rastreos como para registros. OTEL_EXPORTER_OTLP_PROTOCOL (y sus variantes _TRACES_PROTOCOL / _LOGS_PROTOCOL) no se respetan — se usa gRPC en cualquier caso.

Métricas

Al usar los transportes SSE o HTTP transmitible, habilite las métricas de Prometheus con el indicador --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étricas disponibles:

MétricaTipoDescripción
mcp_server_operation_duration_secondsHistogramaDuración de las operaciones MCP (etiquetas: mcp_method_name, gen_ai_tool_name, error_type, network_transport, mcp_protocol_version)
mcp_server_session_duration_secondsHistogramaDuración de las sesiones de cliente MCP (etiquetas: network_transport, mcp_protocol_version)
http_server_request_duration_secondsHistogramaDuración de las solicitudes del servidor HTTP (de otelhttp)

Nota: Las métricas solo están disponibles cuando se usan los transportes SSE o HTTP transmitible. No están disponibles con el transporte stdio.

Registro de solicitudes lentas

El indicador --slow-request-threshold emite un evento de registro estructurado cada vez que una solicitud MCP (invocación de herramienta, lista, lectura de recurso, etc.) excede la duración dada. Es útil para diagnosticar consultas y llamadas a herramientas lentas sin ahogarse en el registro de depuración completo.

# 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

El evento de registro lleva estos atributos estructurados:

AtributoDescripción
mcp.methodEl método MCP (p. ej., tools/call, tools/list, resources/read)
durationDuración observada de la solicitud
thresholdUmbral configurado
toolNombre de la herramienta (solo presente para métodos tools/call)
errorValor de error, cuando la solicitud falló (contexto de mejor esfuerzo; el contenido está controlado por el envoltorio de error ascendente)
error.typeClasificación de error de cardinalidad limitada (_OTHER para errores sin tipo)

El registro de solicitudes lentas funciona en todos los transportes (incluido stdio) y no requiere --metrics. El umbral predeterminado de 0 lo deshabilita por completo. Las herramientas proxy pasan por tools/call y se cubren automáticamente.

Rastreo

El rastreo distribuido se configura mediante variables de entorno estándar OTEL_* y funciona independientemente del indicador --metrics. Cuando OTEL_EXPORTER_OTLP_ENDPOINT está configurado, el servidor exporta rastreos a través de 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

Los tramos de llamadas a herramientas siguen la nomenclatura semconv (tools/call <tool_name>) e incluyen atributos como gen_ai.tool.name, mcp.method.name y mcp.session.id. El servidor también admite la propagación de contexto de rastreo W3C desde el campo _meta de las solicitudes de llamadas a herramientas.

Registros

Cuando OTEL_EXPORTER_OTLP_ENDPOINT (o el específico de señal OTEL_EXPORTER_OTLP_LOGS_ENDPOINT) está configurado — el mismo disparador que habilita el rastreo — el servidor también exporta registros estructurados a través de OTLP/gRPC además de la salida de texto plano existente en stderr. El puente otelslog adjunta automáticamente trace_id y span_id del tramo activo, por lo que los registros se correlacionan con los rastreos que el servidor ya emite.

El registro en stderr no cambia cuando el registro OTLP está habilitado; puede seguir confiando en los registros del contenedor o redirigir stderr a /dev/null si lo prefiere.

# 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

El transporte es OTLP/gRPC (puerto predeterminado 4317). Los registros se pueden enviar directamente a cualquier backend gestionado que acepte OTLP/gRPC — por ejemplo, Grafana Cloud — apuntando OTEL_EXPORTER_OTLP_LOGS_ENDPOINT (o el genérico OTEL_EXPORTER_OTLP_ENDPOINT) al endpoint gRPC remoto y suministrando autenticación a través de OTEL_EXPORTER_OTLP_LOGS_HEADERS (o OTEL_EXPORTER_OTLP_HEADERS), reflejando el ejemplo de rastreo anterior. Un colector OTel local es opcional — útil para distribución en abanico, procesamiento por lotes o enrutamiento multi-backend, pero no es obligatorio.

Las variantes específicas de señal 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 y OTEL_EXPORTER_OTLP_LOGS_COMPRESSION se respetan y anulan sus contrapartes genéricas OTEL_EXPORTER_OTLP_* — consulte la especificación del exportador OTel para la lista completa y las reglas de precedencia.

Si el colector configurado es inaccesible, los registros se almacenan en búfer en memoria (cola predeterminada: 2048) y los registros más antiguos se descartan una vez que la cola se llena. El proceso continúa sin bloquear el servicio. Configure un colector OTel local si necesita un almacenamiento en búfer sin pérdidas durante interrupciones.

Los registros también se exportan bajo el transporte stdio, lo que facilita la centralización de registros desde instancias locales de mcp-grafana invocadas por clientes IDE.

Ejemplo de Docker con métricas, rastreo y registros:

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

Resolución de problemas

Compatibilidad de versiones de Grafana

Si encuentra el siguiente error al usar herramientas relacionadas con fuentes de datos:

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

Esto generalmente indica que está usando una versión de Grafana anterior a la 9.0. El endpoint de API /datasources/uid/{uid} se introdujo en Grafana 9.0, y las operaciones de fuentes de datos fallarán en versiones anteriores.

Solución: Actualice su instancia de Grafana a la versión 9.0 o posterior para resolver este problema.

Desarrollo

¡Las contribuciones son bienvenidas! Por favor, abra un issue o envíe un pull request si tiene alguna sugerencia o mejora.

Este proyecto está escrito en Go. Instale Go siguiendo las instrucciones para su plataforma.

Para ejecutar el servidor localmente en modo STDIO (que es el predeterminado para el desarrollo local), use:

make run

Para ejecutar el servidor localmente en modo SSE, use:

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

También puede ejecutar el servidor usando el transporte SSE dentro de una imagen Docker personalizada. Al igual que la imagen Docker publicada, el punto de entrada de esta imagen personalizada predetermina el modo SSE. Para construir la imagen, use:

make build-image

Y para ejecutar la imagen en modo SSE (el predeterminado), use:

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

Si necesita ejecutarlo en modo STDIO en su lugar, anule la configuración de transporte:

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

Pruebas

Hay tres tipos de pruebas disponibles:

  1. Pruebas unitarias (no requieren dependencias externas):
make test-unit

También puede ejecutar pruebas unitarias con:

make test
  1. Pruebas de integración (requieren que los contenedores Docker estén en funcionamiento):
make test-integration
  1. Pruebas en la nube (requieren instancia de Grafana Cloud y credenciales):
make test-cloud

Nota: Las pruebas en la nube se configuran automáticamente en CI. Para el desarrollo local, necesitará configurar su propia instancia de Grafana Cloud y credenciales.

Las pruebas de integración más completas requerirán una instancia de Grafana ejecutándose localmente en el puerto 3000; puede iniciar una con Docker Compose:

docker-compose up -d

Las pruebas de integración se pueden ejecutar con:

make test-all

Si está añadiendo más herramientas, por favor añada pruebas de integración para ellas. Las pruebas existentes deberían ser un buen punto de partida.

Linting

Para analizar el código, ejecute:

make lint

Esto incluye un linter personalizado que verifica comas no escapadas en las etiquetas de struct jsonschema. Las comas en los campos description deben escaparse con \\, para evitar el truncamiento silencioso. Puede ejecutar solo este linter con:

make lint-jsonschema

Consulte la documentación del Linter JSONSchema para más detalles.

Licencia

Este proyecto está licenciado bajo la Licencia Apache, Versión 2.0.