Grafana

oficial

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

GitHub

3.4k

¿Qué puedes hacer con Grafana MCP?

Buscar e inspeccionar tableros — Usa search_dashboards y get_dashboard_summary para encontrar tableros y obtener resúmenes compactos sin JSON completo.
Consultar Prometheus y Loki — Ejecuta consultas PromQL y LogQL contra tus fuentes de datos, incluyendo metadatos y percentiles de histogramas.
Gestionar alertas — Lista, crea, actualiza y elimina reglas de alerta, además de ver políticas de notificación y puntos de contacto.
Generar enlaces profundos — Crea URLs precisas a tableros, paneles y Explore con rangos de tiempo mediante las herramientas de navegación.
Ejecutar consultas de panel — Ejecuta la consulta de un panel de tablero con rangos de tiempo y variables personalizados usando run_panel_query.

Documentación

Servidor MCP de Grafana

Un servidor de Model Context Protocol (MCP) para Grafana.

Esto proporciona acceso a tu instancia de Grafana y al ecosistema circundante.

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 por la URL de tu instancia (por ejemplo, https://myinstance.grafana.net). Consulta Uso para más opciones de instalación, incluidas Docker, binario y Helm.

Requisitos

Se requiere Grafana versión 9.0 o posterior para disfrutar de todas las funcionalidades. Algunas funciones, especialmente las operaciones relacionadas con fuentes de datos, pueden no funcionar correctamente con versiones anteriores debido a la falta de endpoints de API.

Funciones

La siguiente lista de funciones está actualmente disponible en el servidor MCP. Esta lista tiene únicamente fines informativos y no representa una hoja de ruta ni un compromiso con funciones futuras.

Dashboards

Buscar dashboards: Encuentra dashboards por título u otros metadatos
Obtener dashboard por UID: Recupera los detalles completos de un dashboard usando su identificador único. Advertencia: Los dashboards grandes pueden consumir una cantidad significativa de espacio en la ventana de contexto.
Obtener resumen de dashboard: Obtén una vista compacta de un dashboard, incluyendo 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 de dashboard: Extrae partes específicas de un dashboard 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 dashboard: Modifica dashboards existentes o crea otros nuevos. Advertencia: Requiere el JSON completo del dashboard, lo que puede consumir grandes cantidades de espacio en la ventana de contexto.
Aplicar parche a dashboard: Aplica cambios específicos a un dashboard sin necesidad del JSON completo, reduciendo significativamente el uso de la ventana de contexto para modificaciones puntuales
Obtener consultas de paneles e información de la fuente de datos: Obtén el título, la cadena de consulta y la información de la fuente de datos (incluidos UID y tipo, si están disponibles) de cada panel de un dashboard

Ejecutar consulta de panel

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

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

Gestión de la ventana de contexto

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

Usa get_dashboard_summary para la vista general del dashboard y la planificación de modificaciones
Usa get_dashboard_property con JSONPath cuando solo necesites partes específicas del dashboard
Evita get_dashboard_by_uid a menos que necesites específicamente el JSON completo del dashboard

Fuentes de datos

Listar y obtener información de fuentes de datos: Consulta todas las fuentes de datos configuradas y recupera información detallada de cada una.
- Tipos de fuentes de datos compatibles: 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 indicador --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 (admite consultas métricas instantáneas y de rango) contra fuentes de datos de 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 de Prometheus.
Consultar percentiles de histogramas: Calcula valores de percentiles de histogramas (p50, p90, p95, p99) usando histogram_quantile.

Consultas a Loki

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

Consultas a InfluxDB

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

Consultar InfluxDB: Ejecuta consultas contra fuentes de datos de 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 indicador --enabled-tools.

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

Consultas a CloudWatch

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

Listar espacios de nombres de CloudWatch: Descubre los espacios de nombres disponibles de AWS CloudWatch.
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 de rango de tiempo.

Consultas a Graphite

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

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

Consultas a Athena

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

Listar catálogos de Athena: Descubre los catálogos de datos disponibles (por ejemplo, AwsDataCatalog, conectores de Iceberg).
Listar bases de datos de Athena: Lista las bases de datos de un catálogo de Athena.
Listar tablas de Athena: Lista las tablas de una base de datos de Athena.
Describir tabla de Athena: Obtén los nombres de 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 de variables de plantilla.

Consultas a Snowflake

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

Las consultas pasan a través de la fuente de datos de Snowflake de Grafana (plugin de Grafana Enterprise grafana-snowflake-datasource), por lo que la autenticación la gestiona la configuración de la fuente de datos en Grafana; las credenciales nunca son visibles para el servidor MCP. Este es el mismo modelo que se usa para las herramientas de ClickHouse.

Listar tablas de Snowflake: Descubre tablas (con base de datos, esquema, tipo, recuento de filas y tamaño) mediante INFORMATION_SCHEMA.TABLES. Filtros opcionales por base de datos/esquema.
Describir esquema de tabla: Obtén nombres de columnas, tipos de datos, nulabilidad, valores por defecto y comentarios de una tabla de Snowflake.
Consultar Snowflake: Ejecuta consultas SQL con soporte de sustitución de macros y variables. Útil para consultar las tablas de eventos de Snowflake (por ejemplo, SNOWFLAKE.TELEMETRY.EVENTS) para registros y trazas, o cualquier tabla de usuario.
- Macros compatibles: $__timeFilter(column), $__timeFrom, $__timeTo, $__from, $__to (ms Unix), $__interval (segundos), $__interval_ms y ${varname} para la 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 indicador --enabled-tools.

Consultar Elasticsearch/OpenSearch: Ejecuta consultas de búsqueda contra fuentes de datos de Elasticsearch u OpenSearch usando la sintaxis de consulta de Lucene o el Query DSL de Elasticsearch. Admite filtrado por rango de tiempo y recuperación de registros, métricas o cualquier dato indexado. Devuelve documentos con su índice, ID, campos de origen y una 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 indicador --enabled-tools.

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

Observabilidad de agentes

Nota: Las herramientas de observabilidad de agentes están deshabilitadas por defecto y solo funcionan en Grafana Cloud. Para habilitarlas, añade agento11y a tu indicador --enabled-tools.

Listar y buscar conversaciones: Lista conversaciones recientes de LLM o búscalas con una expresión de filtro (modelo, proveedor, agente, estado, tipo de error, resultados de evaluación y más) en un rango de tiempo. Los resultados de búsqueda incluyen recuentos de errores, resúmenes de valoraciones, resúmenes de evaluaciones e IDs de trazas.
Obtener detalle de conversación: Recupera una sola conversación con todas sus generaciones, incluyendo prompts y salidas.
Obtener detalle y puntuaciones de generación: Recupera una sola generación por ID y sus puntuaciones de evaluación (evaluador, clave de puntuación, valor, aprobado, explicación).
Leer el catálogo de agentes: Lista los agentes que envían telemetría, recupera una versión completa de un agente (el prompt de sistema completo, cada herramienta con su esquema JSON y los modelos en los que se ejecutó), recorre el historial de versiones de un agente y compara agregados de puntuaciones de evaluación por versión. Las versiones efectivas son hashes sha256: que un cambio de herramienta nunca afecta; para un agente que no informa de su propia versión, se aplica hash al prompt de sistema, por lo que una edición del prompt acuña una nueva versión. Las filas del catálogo y de versiones llevan un token_estimate, que vale la pena comprobar antes de recuperar un prompt completo.
Inspeccionar evaluadores y plantillas: Lee los evaluadores de los que proviene una puntuación, las plantillas de las que se derivaron y los proveedores y modelos de juez disponibles para los evaluadores con juez LLM. Con las herramientas de escritura habilitadas, también puedes crear, bifurcar, probar y eliminar evaluadores.
Inspeccionar reglas de evaluación y salvaguardas: Lee las reglas de evaluación asíncronas que vinculan evaluadores al tráfico de producción, y las salvaguardas (reglas de hook) que se ejecutan en línea y pueden advertir o denegar. Con las herramientas de escritura habilitadas, también puedes crearlas, actualizarlas, previsualizarlas y eliminarlas. Las escrituras y las operaciones no persistentes preview_rule y test_evaluator requieren el permiso grafana-agento11y-app.eval:write, otorgado por el rol de administrador de Agento11y.
Seleccionar conversaciones y colecciones guardadas: Lee las conversaciones guardadas (marcadores que dan a una conversación un ID, nombre y etiquetas estables) y las colecciones que las agrupan, incluido el recuento de miembros de cada colección y las colecciones incrustadas en cada fila de conversación guardada. Con las herramientas de escritura habilitadas, también puedes marcar una conversación, crear y editar colecciones, y añadir o eliminar miembros. Estas escrituras requieren el mismo permiso grafana-agento11y-app.eval:write.
Leer y editar suites de prueba: Lista las suites de prueba versionadas con las que se ejecutan experimentos fuera de línea, lee una con su historial completo de versiones y recorre las páginas de casos de prueba de una versión. Con las herramientas de escritura habilitadas, también puedes crear una suite, renombrarla o cambiarle las etiquetas, abrir una versión borrador, publicarla y escribir o eliminar sus casos de prueba. Una versión publicada queda congelada, por lo que una edición implica abrir un nuevo borrador. Estas escrituras requieren grafana-agento11y-app.eval:write.
Leer experimentos fuera de línea: Lista las ejecuciones de evaluación sobre una suite de prueba y lee una con su tasa de aprobación principal, costo y totales de tokens. Profundiza a través de un informe por caso de prueba hasta los ensayos, sus puntuaciones con la explicación de cada juez y sus metadatos de artefactos. Con las herramientas de escritura habilitadas, también puedes renombrar o cambiar las etiquetas de un experimento y cancelar uno en ejecución, lo que requiere grafana-agento11y-app.eval:write. Los experimentos los crean los runners del SDK, no esta herramienta.

Asistente de Grafana

Nota: Las herramientas del asistente están deshabilitadas por defecto y requieren que el plugin Grafana Assistant (grafana-assistant-app) esté instalado en la instancia de Grafana de destino. También son herramientas de escritura (el asistente puede modificar el estado de la pila), por lo que se omiten cuando --disable-write está configurado. Para habilitarlas, añade assistant a tu indicador --enabled-tools.

Preguntar al asistente: Envía un prompt en lenguaje natural a Grafana Assistant y espera la respuesta completa de texto. El asistente puede usar herramientas, métricas, registros y otro contexto de la pila, más amplio que ejecutar una consulta aislada a una fuente de datos. Pasa el contextId devuelto en una llamada de seguimiento para continuar la misma conversación. Las tareas complejas pueden tardar varios minutos; la llamada se bloquea hasta que la respuesta está lista o la solicitud expira (5 minutos).

Incidentes

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

Investigaciones Sift

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

Alertas

Listar y obtener información de reglas de alerta: Ve las reglas de alerta y sus estados (disparando/normal/error/etc.) en Grafana. Soporta tanto reglas gestionadas por Grafana como reglas gestionadas por fuente de datos desde fuentes de datos 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: Ve 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: Ve y gestiona horarios de guardia en Grafana OnCall.
Obtener detalles de turnos: Recupera información detallada sobre turnos de guardia específicos.
Obtener usuarios de guardia actuales: Ve qué usuarios están actualmente de guardia para un horario.
Listar equipos y usuarios: Ve todos los equipos y usuarios de OnCall.
Listar grupos de alertas: Ve 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 indicador --enabled-tools.

Listar equipos: Ve todos los equipos configurados en Grafana.
Listar usuarios: Ve todos los usuarios en una organización de 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 específico de Grafana 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 deeplinks: Crea URLs de deeplink precisas para recursos de Grafana en lugar de depender de la adivinanza de URLs del LLM.
- Enlaces a paneles: Genera enlaces directos a paneles usando su UID (por ejemplo, http://localhost:3000/d/dashboard-uid)
- Enlaces a paneles individuales: Crea enlaces a paneles específicos dentro de paneles de control con el parámetro viewPanel (por ejemplo, http://localhost:3000/d/dashboard-uid?viewPanel=5)
- Enlaces a Explore: Genera enlaces a Grafana Explore con fuentes de datos preconfiguradas (por ejemplo, http://localhost:3000/explore?left={"datasource":"prometheus-uid"})
- Soporte de rango de tiempo: Añade parámetros de rango de tiempo a los enlaces (from=now-1h&to=now)
- Parámetros personalizados: Incluye parámetros de consulta adicionales como variables de panel o intervalos de actualización

Anotaciones

Obtener anotaciones: Consulta anotaciones con filtros. Soporta rango de tiempo, UID de panel, etiquetas y modo de coincidencia.
Crear anotación: Crea una nueva anotación en un panel o panel de control.
Crear anotación de Graphite: Crea anotaciones usando el formato Graphite (what, when, tags, data).
Actualizar anotación: Reemplaza todos los campos de una anotación existente (actualización completa).
Parchear anotación: Actualiza solo campos específicos de una anotación (actualización parcial).
Obtener etiquetas de anotación: Lista las etiquetas de anotación disponibles con filtrado opcional.

Instantáneas

Listar instantáneas: Lista instantáneas de paneles con filtros opcionales de consulta y límite.
Obtener instantánea: Recupera los metadatos de la instantánea y la carga útil del panel mediante la clave de instantánea.
Crear instantánea: Crea una instantánea de panel a partir de una carga útil completa del panel, con opciones opcionales de expiración e instantánea externa.
Eliminar instantánea: Elimina una instantánea por clave de instantánea.

Renderizado

Obtener imagen de panel o panel de control: Renderiza un panel de Grafana o un panel de control completo como 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 panel. También soporta el renderizado de paneles aún no aplicados desde una rama del repositorio de aprovisionamiento (por ejemplo, una vista previa de PR de git-sync) mediante el parámetro opcional provisioningPreview.
- Nota: Requiere que el servicio Grafana Image Renderer esté instalado y configurado.

Aprovisionamiento

Listar repositorios de aprovisionamiento: Lista los repositorios de aprovisionamiento configurados para esta instancia de Grafana (por ejemplo, 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: Aplica en seco un archivo de un repositorio de aprovisionamiento en una rama o commit dado. Devuelve si sería aceptado, la acción del 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 puedes elegir qué herramientas quieres poner a disposición del cliente MCP. Esto es útil si no usas cierta funcionalidad o si no quieres ocupar demasiado de la ventana de contexto. Para deshabilitar una categoría de herramientas, usa el indicador --disable-<category> al iniciar el servidor. Por ejemplo, para deshabilitar las herramientas de OnCall, usa --disable-oncall, o para deshabilitar la generación de deeplinks de navegación, usa --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úrate de que tenga los permisos necesarios según las herramientas que planeas usar. Los permisos listados son las acciones mínimas requeridas; también puedes necesitar scopes apropiados (por ejemplo, datasources:*, dashboards:*, folders:*) dependiendo de tu caso de uso.

Consejo: Si no estás familiarizado con RBAC de Grafana o quieres una configuración más rápida y simple en lugar de configurar muchos scopes granulares, puedes asignar un rol incorporado 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 scopes aplicados manualmente, así que úsalo solo cuando la conveniencia sea más importante que el acceso estricto de privilegio mínimo.

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

Rol de visor: 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, consulta la documentación oficial.

Scopes RBAC

Los scopes definen los recursos específicos a los que se aplican los permisos. Cada acción requiere tanto el permiso apropiado como la combinación de scope.

Patrones de Scope Comunes:

Acceso amplio: Usa comodines * para acceso a toda la organización
- datasources:*: Acceso a todas las fuentes de datos
- dashboards:*: Acceso a todos los paneles
- folders:*: Acceso a todas las carpetas
- teams:*: Acceso a todos los equipos
Acceso limitado: Usa 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 panel 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: Otorga 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 consulta instancias específicas de Prometheus y Loki

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

Acceso específico a paneles: Solo lectura de paneles específicos

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

Herramientas

Herramienta	Categoría	Descripción	Permisos RBAC requeridos	Ámbitos requeridos
`list_teams`	Administración	Listar todos los equipos	`teams:read`	`teams:*` o `teams:id:1`
`list_users_by_org`	Administración	Listar todos los usuarios de una organización	`users:read`	`global.users:*` o `global.users:id:123`
`list_all_roles`	Administración	Listar todos los roles de Grafana	`roles:read`	`roles:*`
`get_role_details`	Administración	Obtener los detalles de un rol de Grafana	`roles:read`	`roles:uid:editor`
`get_role_assignments`	Administración	Listar las asignaciones de un rol	`roles:read`	`roles:uid:editor`
`list_user_roles`	Administración	Listar los roles de los usuarios	`roles:read`	`global.users:id:123`
`list_team_roles`	Administración	Listar los roles de los equipos	`roles:read`	`teams:id:7`
`get_resource_permissions`	Administración	Listar los permisos de un recurso	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	Administración	Describir un tipo de recurso de Grafana	`permissions:read`	`dashboards:*`
`search_dashboards`	Búsqueda	Buscar paneles	`dashboards:read`	`dashboards:*` o `dashboards:uid:abc123`
`get_dashboard_by_uid`	Dashboard	Obtener un panel por uid	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	Dashboard	Actualizar o crear un nuevo panel	`dashboards:create`, `dashboards:write`	`dashboards:`, `folders:` o `folders:uid:xyz789`
`get_dashboard_panel_queries`	Dashboard	Obtener el título del panel, las consultas, el UID de la fuente de datos y su tipo a partir de un panel	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	RunPanelQuery*	Ejecutar una o más consultas de paneles del panel	`dashboards:read`, `datasources:query`	`dashboards:uid:`, `datasources:uid:`
`get_dashboard_property`	Dashboard	Extraer partes específicas de un panel mediante expresiones JSONPath	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	Dashboard	Obtener un resumen compacto de un panel sin el JSON completo	`dashboards:read`	`dashboards:uid:abc123`
`list_datasources`	Fuentes de datos	Listar fuentes de datos	`datasources:read`	`datasources:*`
`get_datasource`	Fuentes de datos	Obtener una fuente de datos por UID o nombre	`datasources:read`	`datasources:uid:prometheus-uid`
`get_query_examples`	Ejemplos*	Obtener consultas de ejemplo para un tipo de fuente de datos	`datasources:read`	`datasources:*`
`query_prometheus`	Prometheus	Ejecutar una consulta contra una fuente de datos Prometheus	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_metadata`	Prometheus	Listar metadatos de métricas	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_metric_names`	Prometheus	Listar los nombres de métricas disponibles	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	Listar nombres de etiquetas que coincidan con un selector	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	Listar los valores de una etiqueta específica	`datasources:query`	`datasources:uid:prometheus-uid`
`query_prometheus_histogram`	Prometheus	Calcular valores de percentiles de histograma	`datasources:query`	`datasources:uid:prometheus-uid`
`list_incidents`	Incident	Listar incidentes en Grafana Incident	Rol Viewer	N/D
`create_incident`	Incident	Crear un incidente en Grafana Incident	Rol Editor	N/D
`add_activity_to_incident`	Incident	Añadir un elemento de actividad a un incidente en Grafana Incident	Rol Editor	N/D
`get_incident`	Incident	Obtener un incidente individual por ID	Rol Viewer	N/D
`query_loki_logs`	Loki	Consultar y recuperar registros usando LogQL (consultas de registros o métricas)	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_names`	Loki	Listar todos los nombres de etiquetas disponibles en los registros	`datasources:query`	`datasources:uid:loki-uid`
`list_loki_label_values`	Loki	Listar valores para una etiqueta de registro específica	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_stats`	Loki	Obtener estadísticas sobre flujos de registros	`datasources:query`	`datasources:uid:loki-uid`
`query_loki_patterns`	Loki	Consultar patrones de registro detectados para identificar estructuras comunes	`datasources:query`	`datasources:uid:loki-uid`
`analyze_loki_labels`	Loki	Auditar una estrategia de etiquetas de Loki (dinámica o estática) y diagnosticar opcionalmente el rendimiento de las consultas	`datasources:query`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Config	Generar un fragmento de `loki.process` de Alloy que aplique las etiquetas aprobadas	N/D	N/D
`query_influxdb`	InfluxDB	Consultar InfluxDB usando InfluxQL (v1) o Flux (v2)	`datasources:query`	`datasources:uid:influxdb-uid`
`list_clickhouse_tables`	ClickHouse*	Listar tablas en una base de datos ClickHouse	`datasources:query`	`datasources:uid:*`
`describe_clickhouse_table`	ClickHouse*	Obtener el esquema de la tabla con tipos de columna	`datasources:query`	`datasources:uid:*`
`query_clickhouse`	ClickHouse*	Ejecutar consultas SQL con sustitución de macros	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	Listar los espacios de nombres disponibles de AWS CloudWatch	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	Listar métricas en un namespace	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	Listar dimensiones para una métrica	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	Ejecutar consultas de métricas de CloudWatch	`datasources:query`	`datasources:uid:*`
`list_athena_catalogs`	Athena*	Listar catálogos de datos de Athena disponibles	`datasources:query`	`datasources:uid:*`
`list_athena_databases`	Athena*	Listar bases de datos en un catálogo de Athena	`datasources:query`	`datasources:uid:*`
`list_athena_tables`	Athena*	Listar tablas en una base de datos de Athena	`datasources:query`	`datasources:uid:*`
`describe_athena_table`	Athena*	Obtener nombres de columnas para una tabla de Athena	`datasources:query`	`datasources:uid:*`
`query_athena`	Athena*	Ejecutar consultas SQL con sustitución de macros	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	Consultar Elasticsearch u OpenSearch usando sintaxis Lucene o Query DSL	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	Consultar Quickwit usando sintaxis Lucene o Query DSL	`datasources:query`	`datasources:uid:quickwit-uid`
`list_snowflake_tables`	Snowflake*	Listar tablas en una base de datos/esquema de Snowflake vía INFORMATION_SCHEMA	`datasources:query`	`datasources:uid:*`
`describe_snowflake_table`	Snowflake*	Obtener esquema de tabla (tipos de columna, nulabilidad, valores por defecto, comentarios)	`datasources:query`	`datasources:uid:*`
`query_snowflake`	Snowflake*	Ejecutar consultas SQL con sustitución de macros/variables	`datasources:query`	`datasources:uid:*`
`alerting_manage_rules`	Alerting	Administrar reglas de alerta (listar, obtener, versiones, crear, actualizar, eliminar)	`alert.rules:read` + `alert.rules:write` para mutaciones	`folders:*` o `folders:uid:alerts-folder`
`alerting_manage_routing`	Alerting	Administrar políticas de notificación, puntos de contacto e intervalos de tiempo	`alert.notifications:read`	Alcance global
`list_oncall_schedules`	OnCall	Listar horarios de Grafana OnCall	`grafana-oncall-app.schedules:read`	Ámbitos específicos del plugin
`get_oncall_shift`	OnCall	Obtener detalles de un turno específico de OnCall	`grafana-oncall-app.schedules:read`	Ámbitos específicos del plugin
`get_current_oncall_users`	OnCall	Obtener usuarios actualmente de guardia para un horario específico	`grafana-oncall-app.schedules:read`	Ámbitos específicos del plugin
`list_oncall_teams`	OnCall	Listar equipos de Grafana OnCall	`grafana-oncall-app.user-settings:read`	Ámbitos específicos del plugin
`list_oncall_users`	OnCall	Listar usuarios de Grafana OnCall	`grafana-oncall-app.user-settings:read`	Ámbitos específicos del plugin
`list_alert_groups`	OnCall	Listar grupos de alertas de Grafana OnCall con opciones de filtrado	`grafana-oncall-app.alert-groups:read`	Ámbitos específicos del plugin
`get_alert_group`	OnCall	Obtener un grupo de alertas específico de Grafana OnCall por su ID	`grafana-oncall-app.alert-groups:read`	Ámbitos específicos del plugin
`get_sift_investigation`	Sift	Recuperar una investigación existente de Sift por su UUID	Rol de visor	N/A
`get_sift_analysis`	Sift	Recuperar un análisis específico de una investigación de Sift	Rol de visor	N/A
`list_sift_investigations`	Sift	Recuperar una lista de investigaciones de Sift con un límite opcional	Rol de visor	N/A
`find_error_pattern_logs`	Sift	Encuentra patrones de error elevados en registros de Loki.	Rol de editor	N/A
`find_slow_requests`	Sift	Encuentra solicitudes lentas desde los datasources de tempo relevantes.	Rol de editor	N/A
`list_pyroscope_label_names`	Pyroscope	Listar nombres de etiquetas que coincidan con un selector	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	Listar valores de etiquetas que coincidan con un selector para un nombre de etiqueta	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	Listar tipos de perfil disponibles	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	Consultar perfiles, métricas o ambos desde Pyroscope	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	Obtener resumen de aserciones para una entidad determinada	Permisos específicos del plugin	Ámbitos específicos del plugin
`agento11y_manage_conversations`	Agent Observability*	Listar, buscar y obtener conversaciones de LLM desde Grafana Agent Observability	`grafana-agento11y-app.conversations:read`	N/A
`agento11y_manage_generations`	Agent Observability*	Obtener detalles de generación de LLM y puntuaciones de evaluación desde Grafana Agent Observability	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_agents`	Agent Observability*	Leer el catálogo de agentes: listar agentes, obtener una versión completa de un agente, listar historial de versiones y agregados de puntuación por versión	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_evaluators`	Agent Observability*	Administrar evaluadores, plantillas de evaluador y el catálogo de jueces (listar, obtener, actualizar o crear, bifurcar, probar, eliminar)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutaciones y pruebas	N/A
`agento11y_manage_eval_rules`	Agent Observability*	Administrar reglas de evaluación y protecciones (listar, obtener, crear, actualizar, previsualizar, eliminar)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutaciones y previsualizaciones	N/A
`agento11y_manage_eval_collections`	Agent Observability*	Administrar conversaciones guardadas y las colecciones que las agrupan (listar, obtener, guardar, crear, actualizar, eliminar, añadir y quitar miembros)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutaciones	N/A
`agento11y_manage_experiments`	Agent Observability*	Leer experimentos sin conexión, sus pruebas, puntuaciones, metadatos de artefactos y facetas de filtro; actualizar y cancelar un experimento	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutaciones	N/A
`agento11y_manage_test_suites`	Agent Observability*	Administrar los conjuntos de pruebas contra los que se ejecutan los experimentos sin conexión, sus versiones y sus casos de prueba (listar, obtener, crear, actualizar, borrador, publicar, actualizar o crear, eliminar)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutaciones	N/A
`ask_assistant`	Assistant*	Enviar un prompt a Grafana Assistant y devolver la respuesta de texto completa (multi-turno vía `contextId`)	Permisos específicos del plugin	Ámbitos específicos del plugin
`generate_deeplink`	Navigation	Generar URLs de enlace profundo precisas para recursos de Grafana	Ninguno (generación de URL de solo lectura)	N/A
`get_annotations`	Annotations	Obtener anotaciones con filtros	`annotations:read`	`annotations:*` o `annotations:id:123`
`create_annotation`	Annotations	Crear una nueva anotación (formato estándar o Graphite)	`annotations:write`	`annotations:*`
`update_annotation`	Annotations	Actualizar campos específicos de una anotación (actualización parcial)	`annotations:write`	`annotations:*`
`get_annotation_tags`	Annotations	Listar etiquetas de anotaciones con filtrado opcional	`annotations:read`	`annotations:*`
`list_snapshots`	Snapshot	Listar instantáneas de paneles con filtros opcionales de consulta y límite	`dashboards:read`	`dashboards:*` o `dashboards:uid:abc123`
`get_snapshot`	Snapshot	Obtener metadatos de instantánea y carga útil del panel por clave de instantánea	`dashboards:read`	`dashboards:*` o `dashboards:uid:abc123`
`create_snapshot`	Snapshot	Crear una instantánea de panel a partir de una carga útil completa del panel	`dashboards:write`	`dashboards:*` o `dashboards:uid:abc123`
`delete_snapshot`	Snapshot	Eliminar una instantánea de panel por clave de instantánea	`dashboards:write`	`dashboards:*` o `dashboards:uid:abc123`
`get_panel_image`	Rendering	Renderizar un panel o panel almacenado — o una vista previa de aprovisionamiento desde una rama de repositorio — como imagen PNG	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	Provisioning	Listar repositorios de aprovisionamiento (p. ej. fuentes git-sync) con su URL de origen, rama, estado de sincronización y salud	`provisioning.repositories:read`	N/A
`validate_provisioning_file`	Provisioning	Aplicar en seco un archivo de un repositorio de aprovisionamiento e informar errores de validación de admisión	`provisioning.repositories:read`	N/A
* Deshabilitado por defecto. Añade la categoría a `--enabled-tools` para habilitarlo.

Referencia de banderas de CLI

El binario mcp-grafana admite varias banderas 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: El 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: /mcp
--server-name: Nombre del servidor utilizado en el handshake de MCP y OTel service.name - predeterminado: mcp-grafana. Sobrescribe la variable de entorno GRAFANA_MCP_SERVER_NAME

Seguridad del transporte HTTP (solo SSE / streamable-http):

La validación de Host/Origin se aplica en todas las rutas del listener — /sse, /mcp, /healthz y /metrics — por lo que un navegador con DNS-rebinding no puede acceder a ninguna de ellas. El transporte stdio no se ve afectado.

--allowed-hosts: Lista de permitidos separada por comas de valores de cabecera Host. Por defecto, variantes de loopback de --address (p. ej., localhost:8000,127.0.0.1:8000,[::1]:8000). Un valor que se analice como vacío (sin establecer, ,, ,, etc.) también recurre a los valores predeterminados para que un error tipográfico no pueda deshabilitar silenciosamente la comprobación. Las solicitudes con una cabecera Host fuera de la lista de permitidos se rechazan con 403. Pasa * para deshabilitar la comprobación — solo es seguro cuando se ejecuta detrás de un proxy inverso de confianza que reescribe Host, o en una red aislada. Las sondas de K8s httpGet y los scrapes externos de /metrics necesitarán un hostname explícito en esta lista, *, o una sonda tcpSocket / un puerto de métricas separado (--metrics-address).
--allowed-origins: Lista de permitidos separada por comas de valores de cabecera Origin. Vacía por defecto — cualquier solicitud que lleve una cabecera Origin se rechaza (los navegadores siempre envían una para solicitudes de origen cruzado, y ningún navegador debería llamar a este servidor directamente). Establece una lista explícita para permitir clientes basados en navegador, o * para deshabilitar la comprobación.

Autenticación del llamador (solo SSE / streamable-http):

Opcionalmente, exige que los clientes MCP se autentiquen ante el servidor. Esto es independiente de las credenciales que el servidor utiliza para acceder a Grafana. Stdio no se ve afectado.

--server-auth-token: Token Bearer que los llamadores deben enviar como Authorization: Bearer <token>. Recurre a la variable de entorno MCP_GRAFANA_SERVER_TOKEN. Cuando se establece, las solicitudes sin un token válido se rechazan con 401 antes de que se ejecute cualquier herramienta. Prefiere la variable de entorno para que el secreto no sea visible en los argumentos del proceso.

La autenticación del llamador solo se aplica cuando --server-auth-token está establecido. Cuando no lo está y el servidor se enlaza a una dirección no-loopback, el servidor se inicia pero registra un error de seguridad — emitido en el nivel de registro error para que no quede oculto por --log-level (loopback y stdio no se ven afectados); una futura versión principal convertirá esto en un error de inicio. Usa TLS (o terminación TLS) siempre que la autenticación del llamador esté habilitada en una dirección no-loopback. Cuando la autenticación del llamador está habilitada, la cabecera Authorization validada se elimina antes de que las solicitudes lleguen a Grafana; combinar --server-auth-token con GRAFANA_FORWARD_HEADERS=Authorization se rechaza al inicio.

Depuración y registro:

--debug: Habilita el modo de depuración para un registro detallado de solicitudes/respuestas HTTP
--log-level: Nivel de registro (debug, info, warn, error) - predeterminado: info

Opciones del cliente de Grafana:

--grafana-timeout: Límite de tiempo para las solicitudes realizadas por el cliente de Grafana. Acepta cadenas de duración de Go (p. ej., 10s, 500ms) - predeterminado: 10s
--include-args-in-spans: Incluir los argumentos de llamada de herramientas en los spans de OpenTelemetry. Solo habilitar en entornos que no sean de producción o cuando se sepa que los argumentos no contienen PII - predeterminado: false

Observabilidad:

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

Gestión de sesiones:

--session-idle-timeout-minutes: Tiempo de inactividad de sesión en minutos. Las sesiones sin actividad durante esta duración se eliminan automáticamente - predeterminado: 30. Establece 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, agento11y, assistant, athena, clickhouse, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery y snowflake. Para habilitar categorías deshabilitadas, agrégalas a la lista (p. ej., "search,datasource,...,snowflake")
--max-loki-log-limit: Número máximo de líneas de registro devueltas por llamada a query_loki_logs - predeterminado: 100. Nota: Establece esto al menos 1 por debajo del valor de 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 datasources
--disable-incident: Deshabilitar herramientas de incidentes
--disable-prometheus: Deshabilitar herramientas de Prometheus
--disable-write: Deshabilitar herramientas de escritura (operaciones de crear/actualizar)
--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 paneles/dashboards)
--disable-snapshot: Deshabilitar herramientas de snapshots
--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
--disable-agento11y: Deshabilitar herramientas de Agent Observability
--disable-assistant: Deshabilitar herramientas de Grafana Assistant

Modo de solo lectura

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

Uso de cuentas de servicio con permisos limitados de solo lectura
Proporcionar a asistentes de IA datos de observabilidad sin capacidad de modificación
Ejecución en entornos de producción donde el acceso de escritura debe estar restringido
Escenarios de prueba y desarrollo donde quieres evitar modificaciones accidentales

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

Herramientas de Dashboards:

update_dashboard

Herramientas de Carpetas:

create_folder

Herramientas de Incidentes:

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

create_snapshot
delete_snapshot

Herramientas de Agent Observability:

agento11y_manage_evaluators (operaciones de upsert, eliminar, fork, probar evaluador)
agento11y_manage_eval_rules (operaciones de crear, actualizar, eliminar, previsualizar regla y guard)
agento11y_manage_eval_collections (guardar y eliminar conversaciones guardadas; crear, actualizar, eliminar colecciones; añadir y eliminar miembros de colección)
agento11y_manage_experiments (operaciones de actualizar y cancelar experimentos)
agento11y_manage_test_suites (crear y actualizar suites de pruebas; crear y publicar versiones; upsert y eliminar casos de prueba)

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 (p. ej., https://myinstance.grafana.net) en lugar de http://localhost:3000 en los ejemplos de configuración siguientes.

Si usas autenticación con token de cuenta de servicio, crea una cuenta de servicio en Grafana con permisos suficientes para usar las herramientas que quieras usar, 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 cómo crear tokens de cuenta de servicio. Consejo: Si no te sientes cómodo configurando alcances RBAC de grano fino, 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 mínimo privilegio.

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

Leyendo 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 solicitud, por lo que los tokens rotados se detectan automáticamente sin reiniciar el servidor.

Esto es particularmente útil en Kubernetes, donde un Secret montado como volumen se actualiza en su lugar cuando el Secret subyacente cambia (normalmente en ~1 minuto). Combinado con la caché de cliente por solicitud — que está indexada por el valor del token — un token rotado produce de forma transparente un nuevo cliente sin reiniciar el 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

El espacio en blanco circundante (incluido un salto de línea final) se recorta del contenido del archivo. Si tanto GRAFANA_SERVICE_ACCOUNT_TOKEN como GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE están establecidos, el token en línea tiene prioridad.

Soporte multi-organización

Puedes especificar con qué organización interactuar usando cualquiera de las siguientes opciones:

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 streamable HTTP (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 solicitudes 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"
      }
    }
  }
}

Encabezados HTTP personalizados

Puede agregar encabezados HTTP arbitrarios a todas las solicitudes de API de Grafana utilizando la variable de entorno GRAFANA_EXTRA_HEADERS. El valor debe ser un objeto JSON que asigne nombres de encabezado a valores.

Ejemplo con encabezados personalizados:

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

Reenvío de encabezados 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 (por ejemplo, un AWS ALB con OIDC), la cookie de sesión de cada usuario debe llegar a Grafana para que pueda asociar la solicitud con el usuario autenticado. La variable de entorno GRAFANA_FORWARD_HEADERS permite esto especificando una lista de permisos separada por comas de nombres de encabezado que se copiarán desde la solicitud HTTP entrante a cada solicitud saliente de la API de Grafana.

Esto solo se aplica cuando se utilizan los transportes SSE (-t sse) o streamable-http (-t streamable-http). No tiene efecto en el 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"
  }
}

Puede reenviar múltiples encabezados separándolos con comas:

GRAFANA_FORWARD_HEADERS=Cookie,X-Session-Id

Los encabezados reenviados se combinan con cualquier encabezado definido en GRAFANA_EXTRA_HEADERS. Si un nombre de encabezado aparece en ambos, el valor de la solicitud entrante tiene prioridad para dicha solicitud.

Tiene varias opciones para instalar mcp-grafana:
- uvx (recomendado): Si tiene uv instalado, no se requiere configuración adicional — uvx descargará y ejecutará automáticamente el servidor:
```
uvx mcp-grafana
```
- Imagen Docker: Utilice la imagen Docker predefinida desde 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 una integración directa con asistentes de IA como Claude Desktop:
  1. Modo STDIO: Para el modo stdio, debe anular 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
```
  Nota — asegure los modos de red: En los modos SSE y streamable-http, el contenedor se vincula a una dirección no loopback (0.0.0.0:8000). Sin un token de llamador, el servidor arranca pero registra un error de seguridad (en el nivel de registro error para que no esté oculto por --log-level; y se negará a arrancar en una futura versión principal). Establezca MCP_GRAFANA_SERVER_TOKEN para requerir un Authorization: Bearer <token> de los clientes (recomendado). El modo STDIO no se ve afectado. Consulte Autenticación de llamador.
  1. Modo SSE: En este modo, el servidor se ejecuta como un servidor HTTP al que los clientes se conectan. Debe exponer el puerto 8000 utilizando 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> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana
```
  1. Modo Streamable HTTP: En este modo, el servidor opera como un proceso independiente que puede manejar múltiples conexiones de clientes. Debe exponer el puerto 8000 utilizando el flag -p: Para este modo debe anular 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> -e MCP_GRAFANA_SERVER_TOKEN=<caller auth token> grafana/mcp-grafana -t streamable-http
```
  Para el modo HTTPS streamable HTTP con certificados TLS del 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> \
  -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
```
- Descargar binario: Descargue la última versión de mcp-grafana desde la página de versiones y colóquela en su $PATH.
- Compilar desde el código fuente: Si tiene instalada una cadena de herramientas de Go, también puede compilar e instalarla 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 su $PATH.
```
GOBIN="$HOME/go/bin" go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest
```
- Desplegar en Kubernetes usando Helm: use el chart de Helm del repositorio 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
```

Agregue la configuración del servidor a su archivo de configuración del cliente. Por ejemplo, para Claude Desktop:

Si usa uvx:

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

Si usa 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 ve Error: spawn mcp-grafana ENOENT en Claude Desktop, debe especificar la ruta completa a mcp-grafana.

Si usa 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 anula el modo SSE predeterminado en la imagen Docker.

Usando VSCode con servidor MCP remoto

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

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

Para el modo HTTPS streamable HTTP 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 agregando el flag -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 solucionar 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 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 de CA TLS para verificación del servidor
--tls-skip-verify: Omitir la verificación del certificado TLS (inseguro, use 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, incluidos:

El cliente principal de OpenAPI de Grafana
Clientes de datasource Prometheus
Clientes de datasource Loki
Clientes de gestión de incidentes
Clientes de investigación Sift
Clientes de alertas
Clientes Asserts

Ejemplos de uso directo de CLI:

Para probar 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

Con solo certificado de CA personalizado:

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

Uso programático:

Si está usando esta biblioteca programáticamente, 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 llamar a NewGrafanaClient directamente (stdio o construcción programática), valide previamente las URLs 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)

Configuración TLS del servidor (solo transporte Streamable HTTP)

Cuando se usa el transporte streamable HTTP (-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 servidor mismo.

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

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

Nota: Estos flags son completamente separados de los flags de TLS del cliente documentados arriba. Los flags de TLS del cliente configuran cómo el servidor MCP se conecta a Grafana, mientras que estos flags TLS del servidor configuran cómo los clientes se conectan al servidor MCP cuando usan el transporte streamable HTTP.

Ejemplo con servidor HTTPS streamable HTTP:

./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 a https://localhost:8443/ en lugar de http://localhost:8000/.

Ejemplo 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 salud

Cuando se usan los transportes SSE (-t sse) o streamable HTTP (-t streamable-http), el servidor MCP expone un endpoint de verificación de salud 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 salud solo está disponible cuando se usan los transportes SSE o streamable HTTP. 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, seguimiento distribuido de OpenTelemetry y exportación de registros de OpenTelemetry, siguiendo las convenciones semánticas de OTel MCP. El seguimiento y la exportación de registros se configuran mediante variables de entorno estándar de OTEL_* y funcionan con cualquier transporte.

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

Métricas

Cuando se usan los transportes SSE o streamable HTTP, habilite las métricas de Prometheus con el flag --metrics:

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

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

Métricas disponibles:

Métrica	Tipo	Descripción
`mcp_server_operation_duration_seconds`	Histograma	Duración de operaciones MCP (etiquetas: `mcp_method_name`, `gen_ai_tool_name`, `error_type`, `network_transport`, `mcp_protocol_version`)
`mcp_server_session_duration_seconds`	Histograma	Duración de sesiones de cliente MCP (etiquetas: `network_transport`, `mcp_protocol_version`)
`http_server_request_duration_seconds`	Histograma	Duración de solicitudes HTTP del servidor (de otelhttp)

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

Registro de solicitudes lentas

El flag --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 lentas y llamadas a herramientas 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:

Atributo	Descripción
`mcp.method`	El método MCP (por ejemplo, `tools/call`, `tools/list`, `resources/read`)
`duration`	Duración de la solicitud observada
`threshold`	Umbral configurado
`tool`	Nombre de la herramienta (solo presente para métodos `tools/call`)
`error`	Valor de error, cuando la solicitud falló (contexto de mejor esfuerzo; el contenido está controlado por el envoltorio de errores ascendente)
`error.type`	Clasificació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 desactiva por completo. Las herramientas proxy pasan a través de tools/call y se cubren automáticamente.

Trazas

El seguimiento distribuido se configura mediante variables de entorno estándar de OTEL_* y funciona independientemente del flag --metrics. Cuando se establece OTEL_EXPORTER_OTLP_ENDPOINT (o el específico de señal OTEL_EXPORTER_OTLP_TRACES_ENDPOINT), el servidor exporta trazas mediante 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 span 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 rastro W3C desde el campo _meta de las solicitudes de llamada a herramientas.

Registros

Cuando se establece OTEL_EXPORTER_OTLP_ENDPOINT (o el específico de señal OTEL_EXPORTER_OTLP_LOGS_ENDPOINT), el servidor también exporta registros estructurados mediante OTLP/gRPC además de la salida existente en texto plano a stderr. El puente otelslog adjunta automáticamente trace_id y span_id desde el span activo, de modo que los registros se correlacionan con las trazas que el servidor ya emite.

Las trazas y los registros resuelven sus endpoints de manera independiente, por lo que las dos señales pueden habilitarse por separado: establecer solo OTEL_EXPORTER_OTLP_TRACES_ENDPOINT habilita el seguimiento sin exportación de registros, establecer solo OTEL_EXPORTER_OTLP_LOGS_ENDPOINT habilita la exportación de registros sin seguimiento, y el genérico OTEL_EXPORTER_OTLP_ENDPOINT habilita ambos.

Si usa el genérico OTEL_EXPORTER_OTLP_ENDPOINT pero desea deshabilitar la exportación de registros (por ejemplo, su backend no admite LogsService), establezca:

OTEL_LOGS_EXPORTER=none

Esto evita que el servidor cree un exportador de registros OTLP independientemente de la configuración del endpoint, evitando errores como unknown service opentelemetry.proto.collector.logs.v1.LogsService.

El registro de stderr no cambia cuando el registro OTLP está habilitado; puede continuar 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 administrado 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 proporcionando autenticación mediante OTEL_EXPORTER_OTLP_LOGS_HEADERS (o OTEL_EXPORTER_OTLP_HEADERS), replicando el ejemplo de trazado anterior. Un colector OTel local es opcional — útil para fan-out, agrupación o enrutamiento multi-backend, pero no es necesario.

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 obtener la lista completa y las reglas de precedencia.

Si el colector configurado no está disponible, 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 mediante el transporte stdio, lo que facilita centralizar los registros de instancias locales de mcp-grafana invocadas por clientes IDE.

Ejemplo de Docker con métricas, trazado 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

Solució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á utilizando 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! Abra un issue o envíe una solicitud de extracción si tiene sugerencias o mejoras.

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:

Pruebas unitarias (sin dependencias externas requeridas):

make test-unit

También puede ejecutar pruebas unitarias con:

make test

Pruebas de integración (requiere que los contenedores Docker estén en funcionamiento):

make test-integration

Pruebas en la nube (requiere instancia de Grafana en la nube 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.

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á agregando más herramientas, agregue pruebas de integración para ellas. Las pruebas existentes deberían ser un buen punto de partida.

Linting

Para hacer lint del código, ejecute:

make lint

Esto incluye un linter personalizado que verifica comas sin escapar en etiquetas de estructura jsonschema. Las comas en los campos description deben escaparse con \\, para evitar truncamiento silencioso. Puede ejecutar solo este linter con:

make lint-jsonschema

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

Licencia

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