Grafana

oficial

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

GitHub

3.5k

Prueba este MCPPatrocinado

¿Qué puedes hacer con Grafana MCP?

Buscar e inspeccionar paneles — Solicita paneles por título, carpeta, etiqueta o estado de favorito, y luego obtén resúmenes, versiones o propiedades específicas de JSONPath como $.title mediante search_dashboards, get_dashboard_summary o get_dashboard_property.
Consultar Prometheus y Loki — Ejecuta consultas PromQL o LogQL, obtén metadatos de métricas/etiquetas y calcula percentiles de histogramas (p50–p99) directamente desde tus fuentes de datos.
Gestionar alertas e incidentes — Lista o crea reglas de alerta, verifica estados de activación y busca o actualiza registros de Incidentes de Grafana con campos personalizados.
Explorar datos SQL y de CloudWatch — Lista tablas, describe esquemas y ejecuta SQL con macros en ClickHouse, Snowflake, Athena, MySQL, PostgreSQL o MSSQL; también consulta métricas de CloudWatch por espacio de nombres y dimensión.
Renderizar paneles y generar enlaces — Obtén un panel o tablero como imagen PNG, o crea enlaces profundos precisos a tableros, paneles y Explore con rangos de tiempo y variables.

Documentación

Servidor MCP de Grafana

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

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

Inicio Rápido

Requiere uv. Agrega 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 la versión 9.0 o posterior de Grafana para funcionalidad completa. Algunas características, particularmente las operaciones relacionadas con fuentes de datos, pueden no funcionar correctamente con versiones anteriores debido a endpoints de API faltantes.

Características

La siguiente lista de características está actualmente disponible en el servidor MCP. Esta lista es solo con fines informativos y no representa una hoja de ruta ni un compromiso con características futuras.

Paneles de control

Buscar paneles de control: Encuentra paneles de control por título, UID de carpeta, etiqueta o estado de marcado como favorito
Obtener panel de control por UID: Recupera los detalles completos del panel de control usando su identificador único. Pasa el version opcional para cargar una instantánea guardada en lugar del panel de control actual. Advertencia: Los paneles de control grandes pueden consumir espacio significativo de la ventana de contexto.
Listar versiones del panel de control: Lista las versiones guardadas de un panel de control como metadatos compactos (número de versión, autor, marca de tiempo, mensaje de guardado)
Obtener resumen del panel de control: Obtén una vista general compacta de un panel de control que incluya título, cantidad 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 de control: Extrae partes específicas de un panel de control 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 de control: Modifica paneles de control existentes o crea nuevos. Advertencia: Requiere el JSON completo del panel de control, lo que puede consumir grandes cantidades de espacio de la ventana de contexto.
Aplicar parche al panel de control: Aplica cambios específicos a un panel de control sin requerir el JSON completo, reduciendo significativamente el uso de la ventana de contexto para modificaciones específicas
Obtener consultas de paneles e información de fuentes 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á disponible) de cada panel en un panel de control

Ejecutar Consulta de Panel

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

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

Gestión de la Ventana de Contexto

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

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

Fuentes de datos

Listar y obtener información de fuentes de datos: Ve todas las fuentes de datos configuradas y recupera información detallada sobre 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, agrega 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 consultas.

Consultas a Prometheus

Consultar Prometheus: Ejecuta consultas PromQL (admite consultas de métricas tanto instantáneas como 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, agrega 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 Fuentes de Datos SQL

Nota: Las herramientas SQL están deshabilitadas por defecto. Para habilitarlas, agrega sql a tu indicador --enabled-tools. Los alias de compatibilidad hacia atrás clickhouse, snowflake y athena también funcionan.

Las herramientas SQL unificadas admiten ClickHouse, Snowflake, Athena, MySQL, PostgreSQL y MSSQL a través de un solo conjunto de herramientas. Las consultas pasan por los plugins de fuentes de datos de Grafana, por lo que la autenticación se maneja mediante la configuración de la fuente de datos: las credenciales nunca son vistas por el servidor MCP.

Listar bases de datos/esquemas/catálogos: Descubre unidades organizativas para una fuente de datos SQL. Para Athena, omite el catálogo para listar catálogos, o pasa un catálogo para listar bases de datos.
Listar tablas: Lista tablas en una base de datos o esquema con metadatos (recuentos de filas, tamaños cuando estén disponibles).
Describir esquema de tabla: Obtén nombres de columnas, tipos, nulabilidad, valores predeterminados y comentarios.
Consultar SQL: Ejecuta consultas SQL con sustitución de macros específica de la fuente de datos ($__timeFilter(col), $__from/$__to, $__interval, ${varname}), aplicación automática de límites y soporte de variables de plantilla.

Consultas a CloudWatch

Nota: Las herramientas de CloudWatch están deshabilitadas por defecto. Para habilitarlas, agrega 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 Google Cloud Logging

Nota: Las herramientas de Google Cloud Logging están deshabilitadas por defecto. Para habilitarlas, agrega cloudlogging a tu indicador --enabled-tools. Requiere el plugin de fuente de datos de Google Cloud Logging (googlecloud-logging-datasource) versión 1.8.0 o posterior, que necesita Grafana 11.2+. Las versiones anteriores del plugin devuelven un diseño de respuesta diferente y query_cloud_logging informa un error solicitando una actualización.

Listar proyectos de Cloud Logging: Descubre los IDs de proyectos de GCP desde los cuales la fuente de datos puede leer registros.
Listar buckets y vistas de Cloud Logging: Descubre buckets de registros y vistas de registros para delimitar una consulta.
Consultar Cloud Logging: Ejecuta filtros del lenguaje de consulta de Cloud Logging (por ejemplo, resource.type="k8s_container" AND severity>=ERROR) con rango de tiempo y límite; devuelve entradas de la más reciente a la más antigua con severidad, cuerpo, etiquetas e ID de seguimiento. La autenticación de GCP se maneja mediante la configuración de la fuente de datos.

Consultas a Graphite

Nota: Las herramientas de Graphite están deshabilitadas por defecto. Para habilitarlas, agrega 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 disponibles de Graphite y sus valores.
Consultar densidad de Graphite: Consulta la densidad de métricas de Graphite para un patrón dado.

Consultas a Elasticsearch/OpenSearch

Nota: Las herramientas de Elasticsearch/OpenSearch están deshabilitadas por defecto. Para habilitarlas, agrega 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 Lucene o el DSL de consultas 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 puntuación de relevancia opcional.

Consultas a Quickwit

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

Consultar Quickwit: Ejecuta consultas de búsqueda contra fuentes de datos de Quickwit usando la sintaxis de consulta Lucene o un DSL de consultas parcialmente 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 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, agrega 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 conteos de errores, resúmenes de calificaciones, resúmenes de evaluaciones e IDs de trazas.
Obtener detalle de conversación: Recupera una sola conversación con todas sus generaciones, incluidos 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 (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 reporta versión propia, se hashea el prompt de sistema, por lo que una edición del prompt genera una nueva versión. Las filas de catálogo y versiones llevan un token_estimate, que vale la pena verificar 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 evaluadores LLM-judge. Con herramientas de escritura habilitadas, también crea, bifurca, prueba y elimina evaluadores.
Inspeccionar reglas de evaluación y guardas: Lee las reglas de evaluación asíncronas que vinculan evaluadores al tráfico de producción y las guardas (reglas de hook) que se ejecutan en línea y pueden advertir o denegar. Con herramientas de escritura habilitadas, también crea, actualiza, previsualiza y elimina estas. Las escrituras y las operaciones no persistentes preview_rule y test_evaluator requieren el permiso grafana-agento11y-app.eval:write, otorgado por el rol Agento11y Admin.
Curar 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 conteo de miembros de cada colección y las colecciones incrustadas en cada fila de conversación guardada. Con herramientas de escritura habilitadas, también marca una conversación, crea y edita colecciones, y agrega o elimina miembros. Estas escrituras requieren el mismo permiso grafana-agento11y-app.eval:write.
Leer y editar suites de prueba: Lista las suites de prueba versionadas contra las que se ejecutan experimentos fuera de línea, lee una con su historial de versiones completo y recorre las páginas de casos de prueba de una versión. Con herramientas de escritura habilitadas, también crea una suite, la renombra o reetiqueta, abre una versión borrador, la publica y escribe o elimina sus casos de prueba. Una versión publicada está congelada, por lo que una edición significa 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 herramientas de escritura habilitadas, también renombra o reetiqueta un experimento y cancela uno en ejecución, lo que requiere grafana-agento11y-app.eval:write. Los experimentos son creados por runners del SDK, no por esta herramienta.

Grafana Assistant

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

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

Incidents

Buscar, crear y actualizar incidentes: Gestiona incidentes en Grafana Incident, incluida la búsqueda, creación, adición de actividades y lectura o configuración de campos personalizados.

Sift Investigations

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 específica de Sift 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).

Alerting

Listar y obtener información de reglas de alerta: Ve las reglas de alerta y sus estados (disparando/normal/error/etc.) en Grafana. Admite reglas gestionadas por Grafana y 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: Ve políticas de notificación, puntos de contacto e intervalos de tiempo. Admite puntos de contacto gestionados por Grafana y 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, incluidos 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.

Admin

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

Listar equipos: Ve todos los equipos configurados en Grafana.
Listar usuarios: Ve 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 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 (dashboard, 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.

User

Información de usuario: Obtén la identidad actual de Grafana: login, correo electrónico, nombre, si es administrador de Grafana (servidor), la organización actual y las organizaciones a las que la credencial puede acceder (con roles). Úsalo para descubrir valores válidos de orgId para solicitudes multi-organización.

Navigation

Generar deeplinks: Crea URLs de deeplink precisas para recursos de Grafana en lugar de depender de adivinanzas de URL del LLM.
- Enlaces de dashboard: Genera enlaces directos a dashboards usando su UID (p. ej., http://localhost:3000/d/dashboard-uid)
- Enlaces de panel: Crea enlaces a paneles específicos dentro de dashboards con el parámetro viewPanel (p. ej., http://localhost:3000/d/dashboard-uid?viewPanel=5)
- Enlaces de Explore: Genera enlaces a Grafana Explore con fuentes de datos preconfiguradas (p. ej., http://localhost:3000/explore?schemaVersion=1&panes={"a":{"datasource":"prometheus-uid"}}). Grafana anterior a 10.2 no entiende panes, por lo que se emite el formato heredado ?left={...} para esas versiones.
- Soporte de rango de tiempo: Agrega 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 dashboard o intervalos de actualización

Annotations

Obtener anotaciones: Consulta anotaciones con filtros. Admite rango de tiempo, UID de dashboard, etiquetas y modo de coincidencia.
Crear anotación: Crea una nueva anotación en un dashboard o panel.
Crear anotación Graphite: Crea anotaciones usando 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).
Eliminar anotación: Elimina permanentemente una anotación por ID.
Obtener etiquetas de anotación: Lista las etiquetas de anotación disponibles con filtrado opcional.

Snapshots

Listar snapshots: Lista snapshots de dashboards con filtros opcionales de consulta y límite.
Obtener snapshot: Recupera metadatos de snapshot y payload de dashboard por clave de snapshot.
Crear snapshot: Crea un snapshot de dashboard a partir de un payload completo de dashboard, con opciones opcionales de expiración y snapshot externo.
Eliminar snapshot: Elimina un snapshot por clave de snapshot.

Rendering

Obtener imagen de panel o dashboard: Renderiza un panel de dashboard de Grafana o un dashboard completo como imagen PNG. Devuelve la imagen como datos codificados en base64 para usar en informes, alertas o presentaciones. Admite personalización de dimensiones, rango de tiempo, tema, escala y variables de dashboard. También admite renderizar dashboards aún no aplicados desde una rama de repositorio de aprovisionamiento (p. ej., 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.

Provisioning

Listar repositorios de aprovisionamiento: Lista los repositorios de aprovisionamiento configurados para esta instancia de Grafana (p. 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: 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 de destino 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 flag --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 (p. ej., datasources:*, dashboards:*, folders:*) según 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 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 scopes aplicados manualmente, así que úsalo solo cuando la conveniencia sea más importante que el acceso estricto de privilegios mínimos.

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

Rol Viewer: Requerido para operaciones de solo lectura (listar incidentes, obtener investigaciones)
Rol 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: Use comodines * para acceso a nivel de organización
- datasources:* - Acceso a todos los datasources
- 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 un datasource específico de Prometheus
- 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 datasources: Consulte solo instancias específicas de Prometheus y Loki

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

Acceso específico a dashboards: Lea solo dashboards 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 en 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 detalles de un rol de Grafana	`roles:read`	`roles:uid:editor`
`get_role_assignments`	Administración	Listar asignaciones para un rol	`roles:read`	`roles:uid:editor`
`list_user_roles`	Administración	Listar roles para usuarios	`roles:read`	`global.users:id:123`
`list_team_roles`	Administración	Listar roles para equipos	`roles:read`	`teams:id:7`
`get_resource_permissions`	Administración	Listar permisos para un recurso	`permissions:read`	`dashboards:uid:abcd1234`
`get_resource_description`	Administración	Describir un tipo de recurso de Grafana	`permissions:read`	`dashboards:*`
`user_info`	Usuario	Identidad actual, capacidades y organizaciones accesibles	Ninguno (usuario con sesión iniciada)	—
`search_dashboards`	Búsqueda	Buscar paneles por consulta, UID de carpeta, etiqueta o destacados	`dashboards:read`	`dashboards:*` o `dashboards:uid:abc123`
`get_dashboard_by_uid`	Panel	Obtener un panel por uid, opcionalmente una versión guardada	`dashboards:read`	`dashboards:uid:abc123`
`list_dashboard_versions`	Panel	Listar versiones guardadas de un panel (versión, autor, hora, mensaje)	`dashboards:read`	`dashboards:uid:abc123`
`update_dashboard`	Panel	Actualizar o crear un nuevo panel	`dashboards:create`, `dashboards:write`	`dashboards:`, `folders:` o `folders:uid:xyz789`
`get_dashboard_panel_queries`	Panel	Obtener título del panel, consultas, UID y tipo de fuente de datos de un panel	`dashboards:read`	`dashboards:uid:abc123`
`run_panel_query`	EjecutarConsultaPanel*	Ejecutar una o más consultas de paneles	`dashboards:read`, `datasources:query`	`dashboards:uid:`, `datasources:uid:`
`get_dashboard_property`	Panel	Extraer partes específicas de un panel usando expresiones JSONPath	`dashboards:read`	`dashboards:uid:abc123`
`get_dashboard_summary`	Panel	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 nombres de métricas disponibles	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_names`	Prometheus	Listar nombres de etiquetas que coinciden con un selector	`datasources:query`	`datasources:uid:prometheus-uid`
`list_prometheus_label_values`	Prometheus	Listar valores para 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`	Incidente	Listar incidentes en Grafana Incident, opcionalmente con sus valores de campos personalizados	Rol de visor	N/A
`create_incident`	Incidente	Crear un incidente en Grafana Incident, opcionalmente estableciendo campos personalizados	Rol de editor	N/A
`add_activity_to_incident`	Incidente	Agregar un elemento de actividad a un incidente en Grafana Incident	Rol de editor	N/A
`update_incident`	Incidente	Actualizar un incidente en Grafana Incident (estado, gravedad, título o campos personalizados)	Rol de editor	N/A
`get_incident`	Incidente	Obtener un solo incidente por ID, incluidos sus campos personalizados	Rol de visor	N/A
`list_incident_custom_fields`	Incidente	Listar los campos personalizados configurados para incidentes, con sus tipos y opciones de selección	Rol de visor	N/A
`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 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 (en vivo o estática) y opcionalmente diagnosticar el rendimiento de consultas	`datasources:query`	`datasources:uid:loki-uid`
`suggest_loki_alloy_label_config`	Configuración	Generar un fragmento de Alloy `loki.process` que aplique etiquetas aprobadas	N/A	N/A
`query_influxdb`	InfluxDB	Consulta InfluxDB usando InfluxQL (v1) o Flux (v2)	`datasources:query`	`datasources:uid:influxdb-uid`
`list_sql_databases`	SQL*	Lista bases de datos, esquemas o catálogos de una fuente de datos SQL	`datasources:query`	`datasources:uid:*`
`list_sql_tables`	SQL*	Lista tablas en una fuente de datos SQL	`datasources:query`	`datasources:uid:*`
`describe_sql_table`	SQL*	Obtén el esquema de columnas de una tabla	`datasources:query`	`datasources:uid:*`
`query_sql`	SQL*	Ejecuta consultas SQL con sustitución de macros	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_namespaces`	CloudWatch*	Lista los espacios de nombres de AWS CloudWatch disponibles	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_metrics`	CloudWatch*	Lista métricas en un espacio de nombres	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimensions`	CloudWatch*	Lista dimensiones para una métrica	`datasources:query`	`datasources:uid:*`
`list_cloudwatch_dimension_values`	CloudWatch*	Lista valores para una clave de dimensión	`datasources:query`	`datasources:uid:*`
`query_cloudwatch`	CloudWatch*	Ejecuta consultas de métricas de CloudWatch	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_projects`	Cloud Logging*	Lista proyectos de GCP legibles por una fuente de datos de Google Cloud Logging	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_buckets`	Cloud Logging*	Lista buckets de registros en un proyecto de GCP	`datasources:query`	`datasources:uid:*`
`list_cloud_logging_views`	Cloud Logging*	Lista vistas de registros en un bucket de registros	`datasources:query`	`datasources:uid:*`
`query_cloud_logging`	Cloud Logging*	Consulta registros con el lenguaje de consulta de Cloud Logging	`datasources:query`	`datasources:uid:*`
`query_elasticsearch`	Elasticsearch/OpenSearch*	Consulta Elasticsearch u OpenSearch usando sintaxis Lucene o Query DSL	`datasources:query`	`datasources:uid:datasource-uid`
`query_quickwit`	Quickwit*	Consulta Quickwit usando sintaxis Lucene o Query DSL	`datasources:query`	`datasources:uid:quickwit-uid`
`alerting_manage_rules`	Alerting	Gestiona 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	Gestiona políticas de notificación, puntos de contacto e intervalos de tiempo	`alert.notifications:read`	Ámbito global
`alerting_manage_silences`	Alerting	Gestiona silencios de alertas (listar, obtener, crear, actualizar, expirar)	`alert.instances:read` + `alert.instances:write` para mutaciones	Ámbito global
`list_oncall_schedules`	OnCall	Lista horarios de Grafana OnCall	`grafana-oncall-app.schedules:read`	Ámbitos específicos del plugin
`get_oncall_shift`	OnCall	Obtén detalles de un turno específico de OnCall	`grafana-oncall-app.schedules:read`	Ámbitos específicos del plugin
`get_current_oncall_users`	OnCall	Obtén usuarios actualmente de guardia para un horario específico	`grafana-oncall-app.schedules:read`	Ámbitos específicos del plugin
`list_oncall_teams`	OnCall	Lista equipos de Grafana OnCall	`grafana-oncall-app.user-settings:read`	Ámbitos específicos del plugin
`list_oncall_users`	OnCall	Lista usuarios de Grafana OnCall	`grafana-oncall-app.user-settings:read`	Ámbitos específicos del plugin
`list_alert_groups`	OnCall	Lista 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	Obtén un grupo de alertas específico de Grafana OnCall por su ID	`grafana-oncall-app.alert-groups:read`	Ámbitos específicos del plugin
`update_alert_group`	OnCall	Reconoce, desreconoce, resuelve o desresuelve un grupo de alertas	`grafana-oncall-app.alert-groups:write` (y `:read`)	Ámbitos específicos del plugin
`get_sift_investigation`	Sift	Recupera una investigación Sift existente por su UUID	Rol de visor	N/A
`get_sift_analysis`	Sift	Recupera un análisis específico de una investigación Sift	Rol de visor	N/A
`list_sift_investigations`	Sift	Recupera una lista de investigaciones 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 de las fuentes de datos tempo relevantes.	Rol de editor	N/A
`list_pyroscope_label_names`	Pyroscope	Lista nombres de etiquetas que coinciden con un selector	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_label_values`	Pyroscope	Lista valores de etiquetas que coinciden con un selector para un nombre de etiqueta	`datasources:query`	`datasources:uid:pyroscope-uid`
`list_pyroscope_profile_types`	Pyroscope	Lista tipos de perfil disponibles	`datasources:query`	`datasources:uid:pyroscope-uid`
`query_pyroscope`	Pyroscope	Consulta perfiles, métricas o ambos desde Pyroscope	`datasources:query`	`datasources:uid:pyroscope-uid`
`get_assertions`	Asserts	Obtén un resumen de aserciones para una entidad dada	Permisos específicos del plugin	Ámbitos específicos del plugin
`agento11y_manage_conversations`	Agent Observability*	Lista, busca y obtén conversaciones de LLM desde Grafana Agent Observability	`grafana-agento11y-app.conversations:read`	N/A
`agento11y_manage_generations`	Agent Observability*	Obtén 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*	Lee el catálogo de agentes: lista agentes, obtén una versión de agente completa, lista el historial de versiones y agregados de puntuación por versión	`grafana-agento11y-app.data:read`	N/A
`agento11y_manage_evaluators`	Agent Observability*	Gestiona evaluadores, plantillas de evaluadores y el catálogo de jueces (listar, obtener, upsert, 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*	Gestiona reglas de evaluación y guardias (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*	Gestiona conversaciones guardadas y las colecciones que las agrupan (listar, obtener, guardar, crear, actualizar, eliminar, agregar y quitar miembros)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutaciones	N/A
`agento11y_manage_experiments`	Observabilidad de agentes*	Leer experimentos offline, 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`	Observabilidad de agentes*	Gestionar los conjuntos de pruebas contra los que se ejecutan los experimentos offline, sus versiones y sus casos de prueba (listar, obtener, crear, actualizar, borrador, publicar, upsert, eliminar)	`grafana-agento11y-app.data:read` + `grafana-agento11y-app.eval:write` para mutaciones	N/A
`ask_assistant`	Asistente*	Enviar un prompt a Grafana Assistant y devolver la respuesta de texto completa (multiturno mediante `contextId`)	Permisos específicos del plugin	Ámbitos específicos del plugin
`generate_deeplink`	Navegación	Generar URLs de deeplink precisas para recursos de Grafana	Ninguno (generación de URL de solo lectura)	N/A
`get_annotations`	Anotaciones	Obtener anotaciones con filtros	`annotations:read`	`annotations:*` o `annotations:id:123`
`create_annotation`	Anotaciones	Crear una nueva anotación (formato estándar o Graphite)	`annotations:write`	`annotations:*`
`update_annotation`	Anotaciones	Actualizar campos específicos de una anotación (actualización parcial)	`annotations:write`	`annotations:*`
`delete_annotation`	Anotaciones	Eliminar una anotación por ID	`annotations:delete`	`annotations:*`
`get_annotation_tags`	Anotaciones	Listar etiquetas de anotaciones con filtrado opcional	`annotations:read`	`annotations:*`
`list_snapshots`	Instantánea	Listar instantáneas de paneles con consulta opcional y filtros de límite	`dashboards:read`	`dashboards:*` o `dashboards:uid:abc123`
`get_snapshot`	Instantánea	Obtener metadatos de instantánea y carga útil del panel por clave de instantánea	`dashboards:read`	`dashboards:*` o `dashboards:uid:abc123`
`create_snapshot`	Instantánea	Crear una instantánea de panel a partir de una carga útil completa del panel	`dashboards:write`	`dashboards:*` o `dashboards:uid:abc123`
`delete_snapshot`	Instantánea	Eliminar una instantánea de panel por clave de instantánea	`dashboards:write`	`dashboards:*` o `dashboards:uid:abc123`
`get_panel_image`	Renderizado	Renderizar un panel o panel de control almacenado — o una vista previa de aprovisionamiento desde una rama de repositorio — como imagen PNG	`dashboards:read`	`dashboards:uid:abc123`
`list_provisioning_repositories`	Aprovisionamiento	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`	Aprovisionamiento	Aplicar en seco un archivo de un repositorio de aprovisionamiento e informar errores de validación de admisión	`provisioning.repositories:read`	N/A
`search_docs`	Documentación	Buscar documentación de Grafana o listar grupos de productos (omitir consulta para listar productos)	Ninguno (grafana.com/docs público)	N/A
`get_doc`	Documentación	Obtener una página de documentación; establecer outline_only para encabezados, o section para recuperación acotada	Ninguno (grafana.com/docs público)	N/A
* Deshabilitado por defecto. Añade la categoría a `--enabled-tools` para habilitarlo.

Referencia de Banderas de CLI

El binario mcp-grafana soporta varias banderas de línea de comandos para 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. /healthz y /metrics siempre se sirven en la raíz del servidor, no bajo este prefijo — son endpoints internos exclusivos para sondas y raspadores, y mantenerlos fuera del prefijo de la aplicación facilita exponer la API a través de un proxy inverso sin exponerlos también
--endpoint-path: Ruta del endpoint para el servidor streamable-http, añadida a --base-path - predeterminado: /mcp
--server-name: Nombre del servidor utilizado en el apretón de manos MCP y OTel service.name - predeterminado: mcp-grafana. Sobrescribe la variable de entorno GRAFANA_MCP_SERVER_NAME
--instructions-append: Texto añadido a las instrucciones del servidor devueltas a los clientes MCP al inicializar, para que cada agente conectado lo vea

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

La validación de Host/Origin se aplica en cada ruta del listener MCP — /sse, /mcp y /healthz / /metrics cuando comparten ese listener — por lo que un navegador con rebinding de DNS no puede alcanzar ninguno de ellos. El transporte stdio no se ve afectado. --healthz-address y --metrics-address inician un listener separado que no está envuelto.

--allowed-hosts: Lista de permitidos separada por comas de valores de cabecera Host. Predeterminado a variantes de loopback de --address (p. ej., localhost:8000,127.0.0.1:8000,[::1]:8000). Un valor que se analice como vacío (no establecido, ,, ,, etc.) también vuelve a los valores predeterminados para que un error tipográfico no pueda deshabilitar silenciosamente la verificación. Las solicitudes con una cabecera Host fuera de la lista de permitidos se rechazan con 403. Pasa * para deshabilitar la validación de Host — solo es seguro cuando un proxy inverso de confianza valida Host. Las sondas K8s httpGet y los raspados externos de /metrics necesitarán un nombre de host explícito en esta lista, *, una sonda tcpSocket o un puerto separado (--healthz-address / --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 verificación.
--allow-grafana-url-override: Habilita la selección de X-Grafana-URL. Vuelve a GRAFANA_ALLOW_URL_OVERRIDE; deshabilitado por defecto. Sin una lista de permitidos, los llamadores pueden seleccionar cualquier URL HTTP(S) que el servidor pueda alcanzar.
--allowed-grafana-urls: Lista de permitidos opcional separada por comas de URLs base exactas de Grafana para sobrescrituras de URL. Vuelve a GRAFANA_ALLOWED_URLS. Requiere --allow-grafana-url-override; una bandera vacía explícita deshabilita una lista heredada.

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

Opcionalmente requiere que los clientes MCP se autentiquen al servidor. Esto es separado de las credenciales que el servidor usa para alcanzar Grafana. Stdio no se ve afectado.

--server-auth-token: Token Bearer que los llamadores deben enviar como Authorization: Bearer <token>. Vuelve 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 se aplica solo cuando --server-auth-token está establecido. Cuando no lo está y el servidor se vincula a una dirección que no es de 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 que no sea de 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.

Sobrescrituras de URL de Grafana (solo SSE / streamable-http):

[!ADVERTENCIA] Las sobrescrituras de URL permiten que los llamadores MCP seleccionen destinos HTTP(S) salientes. Una lista de permitidos limita las URLs pero no autentica a los llamadores ni vincula tokens a destinos.

Implementa detrás de un proxy autenticador que autorice cada destino, reemplace la URL y las cabeceras de token proporcionadas por el cliente, y suministre el token correspondiente. Restringe el acceso de red saliente del servidor a destinos aprobados.

Sin una lista de permitidos, un token de solicitud falso puede causar solicitudes a cualquier servicio HTTP(S) alcanzable, incluidos servicios internos y de metadatos.

Establece GRAFANA_ALLOW_URL_OVERRIDE=true (o --allow-grafana-url-override) para habilitar la selección para una flota grande. Para restringir destinos, también establece GRAFANA_ALLOWED_URLS=https://one.example.com,https://two.example.com/grafana (o --allowed-grafana-urls).

Envía estas cabeceras en cada solicitud MCP que seleccione un destino:

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

Si --server-auth-token está configurado, también envía Authorization: Bearer <MCP caller token>. Esto autentica al servidor MCP y es separado de X-Grafana-Service-Account-Token, que es para la instancia de Grafana seleccionada. Tu proxy puede enviar un token de Grafana diferente para cada instancia; el servidor nunca comparte un token configurado entre ellas. La cabecera obsoleta X-Grafana-API-Key también funciona. Una cabecera de URL sin un token de Grafana de solicitud se rechaza. Usa TLS para solicitudes entrantes porque llevan tokens.

La lista de permitidos coincide con URLs base exactas, incluidos esquema, puerto y ruta; no se admiten comodines. La autenticación de Grafana no es una defensa contra SSRF.

Para una URL seleccionada, el servidor no usa GRAFANA_SERVICE_ACCOUNT_TOKEN, GRAFANA_SERVICE_ACCOUNT_TOKEN_FILE, GRAFANA_API_KEY, autenticación básica de entorno, GRAFANA_EXTRA_HEADERS ni certificados de cliente. La verificación TLS permanece habilitada incluso si --tls-skip-verify está establecido; un archivo CA configurado aún se aplica. Las cabeceras reenviadas explícitamente desde esa solicitud aún se aplican. Las redirecciones y otras solicitudes de API de Grafana fuera de la URL base seleccionada se bloquean. Las solicitudes sin X-Grafana-URL conservan el comportamiento habitual de GRAFANA_URL y credenciales de entorno. Esta opción se aplica solo a SSE y HTTP streamable. Para SSE, incluye ambas cabeceras de selección en cada POST de mensaje; las cabeceras en el GET inicial de SSE no se transfieren a las llamadas de herramientas.

Depuración y Registro:

--debug: Habilita el modo de depuración para 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 solicitudes realizadas por el cliente de Grafana. Acepta cadenas de duración de Go (p. ej., 10s, 500ms) - predeterminado: 10s
--include-args-in-spans: Incluye argumentos de llamadas de herramientas en tramos de OpenTelemetry. Solo habilítalo 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ía, las métricas se sirven en el servidor principal
--healthz-address: Dirección separada para /healthz (p. ej., :8080). Si está vacía, /healthz se sirve en el servidor principal. Comparte un listener con --metrics-address cuando las dos direcciones coinciden. Los listeners laterales omiten la validación de Host/Origin.
--slow-request-threshold: Registra un evento cuando cualquier solicitud MCP (invocación de herramienta, lista, lectura de recurso, etc.) tarda 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.

Estadísticas de Uso Anónimas:

--usage-stats: Informe de estadísticas de uso anónimas: enabled, disabled o log (imprime el informe que se enviaría a stderr y no envía nada). Sobrescribe la variable de entorno GRAFANA_USAGE_STATS, que a su vez sobrescribe DO_NOT_TRACK; cualquier valor no reconocido deshabilita el informe. Consulta la sección Estadísticas de uso anónimas.

Gestión de Sesiones:

--session-idle-timeout-minutes: Tiempo de espera 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, cloudlogging, cloudwatch, elasticsearch, examples, graphite, quickwit, runpanelquery y snowflake. Para habilitar categorías deshabilitadas, agréguelas a la lista (por ejemplo, "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: Establezca 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).
--loki-guardrail-mode: Salvaguarda de costo de consulta de Loki para query_loki_logs - predeterminado: off. Loki no aplica max_query_bytes_read en consultas de registro sin un filtro de línea, por lo que un selector amplio sobre un rango extenso puede escanear terabytes; la salvaguarda requiere un selector de flujo selectivo, limita el rango de tiempo efectivo (incluidas duraciones de vector de rango como [30d]) y verifica previamente la estimación de bytes del índice/estadísticas de Loki antes de ejecutar la consulta. shadow registra consultas que serían bloqueadas pero las deja ejecutar (aún paga el viaje de ida y vuelta de índice/estadísticas); enforce las rechaza con orientación de reescritura sobre la que el LLM puede actuar. En VictoriaLogs, la salvaguarda se aplica solo a consultas con forma de selector ({...}) — cuando no se analiza ningún selector (la forma normal de LogsQL sin llaves), la consulta pasa por completo y la verificación del presupuesto de bytes nunca se aplica (sin estimación de índice económica). Respaldo de entorno: GRAFANA_LOKI_GUARDRAIL_MODE.
--loki-guardrail-max-bytes: Bytes máximos que una sola llamada a query_loki_logs puede escanear, estimados a través de la API de índice/estadísticas de Loki - predeterminado: 107374182400 (100 GiB). 0 deshabilita la verificación del presupuesto de bytes. Respaldo de entorno: GRAFANA_LOKI_GUARDRAIL_MAX_BYTES.
--loki-guardrail-max-range: Rango de tiempo efectivo máximo para una sola llamada a query_loki_logs, incluidas duraciones de vector de rango - predeterminado: 24h. Acepta cadenas de duración de Go. 0 deshabilita la verificación de rango. Respaldo de entorno: GRAFANA_LOKI_GUARDRAIL_MAX_RANGE.
--loki-enforced-matchers: Coincidencias de etiquetas LogQL aplicadas con AND a cada consulta nativa de Loki para restringir qué flujos de registro se pueden leer (por ejemplo, environment=~"prod|staging"). Requiere --disable-api. Consulte Aplicación de consultas de Loki.
--loki-label-enumeration-fallback: Qué hacen las herramientas de enumeración de etiquetas cuando las coincidencias negativas aplicadas no pueden limitarlas: reject (predeterminado) o unfiltered. Consulte Aplicación de consultas de Loki.
--disable-search: Deshabilitar herramientas de búsqueda
--disable-datasource: Deshabilitar herramientas de fuente de datos
--disable-incident: Deshabilitar herramientas de incidentes
--disable-prometheus: Deshabilitar herramientas de Prometheus
--disable-write: Deshabilitar herramientas de escritura (operaciones de creación/actualización)
--disable-query: Deshabilitar herramientas de consulta (herramientas que ejecutan una consulta contra una fuente de datos); las herramientas de metadatos y descubrimiento permanecen disponibles
--enable-query: Mantener las herramientas de consulta SQL sin procesar (query_sql, query_influxdb) registradas incluso bajo --disable-write. Equivalente a --enable-write-tools=query_sql,query_influxdb; se mantiene como abreviatura para ese caso común.
--enable-write-tools: Lista separada por comas de nombres de herramientas individuales para mantener registradas incluso bajo --disable-write, para herramientas cuyo comportamiento de escritura está lo suficientemente limitado como para optar por participar de forma independiente (por ejemplo, find_error_pattern_logs,find_slow_requests). No tiene efecto en una herramienta cuya categoría completa está deshabilitada, por ejemplo, a través de --disable-sift.
--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 paneles
--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/paneles)
--disable-snapshot: Deshabilitar herramientas de instantáneas
--disable-cloudwatch: Deshabilitar herramientas de CloudWatch
--disable-cloudlogging: Deshabilitar herramientas de Google Cloud Logging
--disable-examples: Deshabilitar herramientas de ejemplos de consultas
--disable-sql: Deshabilitar herramientas de fuentes de datos SQL (ClickHouse, Snowflake, Athena, MySQL, PostgreSQL, MSSQL). Los alias --disable-clickhouse, --disable-snowflake, --disable-athena también funcionan.
--disable-runpanelquery: Deshabilitar herramientas de ejecución de consultas de panel
--disable-graphite: Deshabilitar herramientas de Graphite
--disable-provisioning: Deshabilitar herramientas de aprovisionamiento
--disable-agento11y: Deshabilitar herramientas de Agent Observability
--disable-assistant: Deshabilitar herramientas de Grafana Assistant
--disable-docs: Deshabilitar herramientas de documentación

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 su instancia de Grafana. Esto es útil para escenarios donde desea proporcionar acceso seguro de solo lectura, como:

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

Cuando --disable-write está habilitado, las siguientes operaciones de escritura están deshabilitadas:

Herramientas de paneles:

update_dashboard

Herramientas de carpetas:

create_folder

Herramientas de incidentes:

create_incident
add_activity_to_incident
update_incident

Herramientas de alertas:

alerting_manage_rules (operaciones de creación, actualización, eliminación)
alerting_manage_silences (operaciones de creación, actualización, eliminación)

Herramientas de OnCall:

update_alert_group

Herramientas de anotaciones:

create_annotation
update_annotation
delete_annotation

Herramientas de Sift:

find_error_pattern_logs (crea investigaciones)
find_slow_requests (crea investigaciones)

Estas solo crean registros efímeros de investigación de Sift a través de la API de Sift — nunca tocan un panel, alerta o fuente de datos de Grafana. Sin ellas, list_sift_investigations/get_sift_investigation/get_sift_analysis no tienen nada que listar u obtener. Pase --enable-write-tools=find_error_pattern_logs,find_slow_requests para mantenerlas registradas bajo --disable-write.

Herramientas de instantáneas:

create_snapshot
delete_snapshot

Herramientas de consulta SQL sin procesar:

Estas ejecutan cualquier consulta que les proporcione sin inspeccionarla, por lo que pueden escribir cuando las credenciales de la fuente de datos lo permitan — query_sql ejecutará un DROP TABLE, query_influxdb ejecutará un DELETE. Por lo tanto, el modo de solo lectura las elimina. Pase --enable-query para mantenerlas cuando se sabe que las credenciales de la fuente de datos son de solo lectura.

query_sql
query_influxdb

Herramientas de Agent Observability:

agento11y_manage_evaluators (operaciones de upsert, eliminación, bifurcación, prueba de evaluador)
agento11y_manage_eval_rules (operaciones de creación, actualización, eliminación, vista previa de reglas y guardas)
agento11y_manage_eval_collections (guardar y eliminar conversaciones guardadas; crear, actualizar, eliminar colecciones; agregar y eliminar miembros de colecciones)
agento11y_manage_experiments (operaciones de actualización y cancelación de experimentos)
agento11y_manage_test_suites (crear y actualizar suites de prueba; crear y publicar versiones; upsert y eliminar casos de prueba)

Todas las operaciones de lectura permanecen disponibles, lo que le permite consultar paneles, ejecutar consultas PromQL/LogQL, listar recursos y recuperar datos. Los lenguajes de consulta que no pueden expresar una escritura — PromQL, LogQL, TraceQL, el DSL de Elasticsearch, Graphite, CloudWatch — mantienen sus herramientas de consulta en modo de solo lectura; solo las herramientas SQL sin procesar enumeradas anteriormente se eliminan.

Modo sin consultas

La bandera --disable-query elimina toda herramienta que ejecute una consulta contra una fuente de datos, mientras deja las herramientas de metadatos y descubrimiento en su lugar. Esto es útil cuando desea un asistente que pueda explorar lo que existe — fuentes de datos, paneles, nombres de métricas, etiquetas, esquemas de tablas — sin ejecutar consultas potencialmente costosas o que revelen datos, por ejemplo, cuando la cuenta de servicio tiene datasources:read pero no datasources:query.

Es la más fuerte de las tres configuraciones de consulta, y prevalece sobre --enable-query:

Banderas	Herramientas de consulta seguras (`query_prometheus`, `query_loki_logs`, `run_panel_query`, …)	Herramientas de consulta SQL sin procesar (`query_sql`, `query_influxdb`)
(ninguna)	registradas	registradas
`--disable-write`	registradas	no registradas
`--disable-write --enable-query`	registradas	registradas
`--disable-query`	no registradas	no registradas
`--disable-query --enable-query`	no registradas	no registradas

Cuando --disable-query está habilitado, las siguientes herramientas no están registradas:

Herramientas de Prometheus:

query_prometheus
query_prometheus_histogram

Herramientas de Loki:

query_loki_logs
query_loki_patterns

query_loki_stats y analyze_loki_labels permanecen registradas: ambas envían un selector a la fuente de datos, pero leen el índice y devuelven recuentos de flujo, fragmento y bytes en lugar del contenido del registro.

Herramientas de Elasticsearch/OpenSearch y Quickwit:

query_elasticsearch
query_quickwit

Herramientas de InfluxDB (también eliminadas por --disable-write, ver arriba):

query_influxdb

Herramientas de fuentes de datos SQL (también eliminadas por --disable-write, ver arriba):

query_sql

Herramientas de Graphite:

query_graphite
query_graphite_density

Herramientas de CloudWatch:

query_cloudwatch

Herramientas de Google Cloud Logging:

query_cloud_logging

Herramientas de Pyroscope:

query_pyroscope

Herramientas de ejecución de consultas de panel:

run_panel_query

Las categorías elasticsearch, quickwit, influxdb y runpanelquery no contienen nada más, por lo que no registran ninguna herramienta cuando las consultas están deshabilitadas. Las herramientas hermanas en todas las demás categorías — list_prometheus_metric_names, list_loki_label_values, describe_sql_table, list_cloudwatch_metrics, list_cloud_logging_projects, y así sucesivamente — permanecen disponibles.

Tenga en cuenta que --disable-query controla las herramientas de consulta y la ruta POST a grafana_api_request-/api/ds/query, pero no vigila todas las rutas a una fuente de datos. En modo de solo lectura, grafana_api_request permite POST a /api/ds/query solo cuando las herramientas de consulta están habilitadas (misma puerta que las herramientas SQL sin procesar — bloqueadas por --disable-write a menos que --enable-query lo anule). get_panel_image, que renderiza un panel en el lado del servidor, no se ve afectado.

Configuración TLS del cliente (para conexiones de 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 verificación de certificado TLS (inseguro)

Configuración TLS del servidor (solo transporte HTTP transmisible):

--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, use la URL de su instancia (por ejemplo, https://myinstance.grafana.net) en lugar de http://localhost:3000 en los ejemplos de configuración a continuación.

Si usa autenticación con token de cuenta de servicio, cree una cuenta de servicio en Grafana con permisos suficientes para usar las herramientas que desea usar, genere un token de cuenta de servicio y cópielo al portapapeles para usarlo en el archivo de configuración. Siga la documentación de cuentas de servicio de Grafana para obtener detalles sobre cómo crear tokens de cuenta de servicio. Consejo: Si no se siente 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 — úselo 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. Migre al uso de GRAFANA_SERVICE_ACCOUNT_TOKEN en su lugar. El nombre de variable anterior 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 nuevamente en cada solicitud, 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 su lugar cuando el Secret subyacente cambia (normalmente en ~1 minuto). Combinado con la caché de cliente por solicitud — que está claveada 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

El espacio en blanco circundante (incluyendo una nueva línea final) se recorta del contenido del archivo. Si tanto GRAFANA_SERVICE_ACCOUNT_TOKEN como 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 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 cuando uses transportes SSE o HTTP transmisible (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.

Selección dinámica de organización (por llamada)

Las opciones anteriores fijan la organización para toda la conexión. Para permitir que una sola conexión apunte a diferentes organizaciones por llamada de herramienta, inicia el servidor con la bandera --dynamic-multi-org. Esto está desactivado por defecto.

Cuando está habilitado, cada herramienta acepta un argumento opcional orgId que anula la organización de la conexión para esa llamada (impulsando tanto la cabecera X-Grafana-Org-Id como, para las APIs de la plataforma de aplicaciones, el namespace resuelto de Kubernetes). Las herramientas de fuentes de datos proxy se descubren adicionalmente en cada organización a la que la credencial puede acceder. Las llamadas que omiten orgId usan la organización predeterminada de la conexión.

Esto solo funciona para credenciales que pertenecen a más de una organización (por ejemplo, un usuario o una identidad en nombre de); un token de cuenta de servicio permanece vinculado a su única organización. Usa la herramienta user_info para descubrir qué valores de orgId son válidos.

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 agregar cabeceras HTTP arbitrarias a todas las solicitudes de la API de Grafana usando la variable de entorno GRAFANA_EXTRA_HEADERS. El valor debe ser un objeto JSON que mapee nombres de cabeceras 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\"}"
      }
    }
  }
}

Proxy SOCKS5

Puedes enrutar todas las solicitudes que este servidor hace a Grafana a través de un proxy SOCKS5 usando la variable de entorno GRAFANA_SOCKS5_PROXY. El proxy está limitado al tráfico de Grafana de este servidor: no modifica las variables globales HTTP_PROXY/HTTPS_PROXY, y cuando se establece, anula su selección de proxy solo para los transportes de Grafana, sin afectar a otros servidores MCP ni a tu sesión de shell. Cuando no se establece, el comportamiento no cambia.

La URL debe usar el esquema socks5:// o socks5h:// (Go los trata de manera idéntica: la resolución de nombres de host se delega al proxy) y puede incluir credenciales, por ejemplo socks5://user:pass@127.0.0.1:1080.

Ejemplo:

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

Una URL de proxy inválida es un error de inicio, y si la construcción de una conexión proxy falla en tiempo de ejecución, el servidor falla de manera segura en lugar de enviar silenciosamente tráfico de Grafana directamente.

Reenvío de Cabeceras desde el Cliente (Solo SSE/HTTP Transmisible)

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 habilita esto especificando una lista de permitidos separada por comas de nombres de cabeceras para copiar desde la solicitud HTTP entrante a cada solicitud saliente de la API de Grafana.

Esto solo se aplica cuando se usan transportes SSE (-t sse) o HTTP transmisible (-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 solicitud entrante tiene prioridad para esa solicitud.

Las cabeceras de contexto de rastreo (traceparent, tracestate, baggage) son la excepción: el servidor propaga el contexto de rastreo por sí mismo, por lo que un valor reenviado nunca anula el que inyecta. Consulta observabilidad.

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 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 integración directa con asistentes de IA como Claude Desktop:
  1. Modo STDIO: Para el modo stdio debes anular explícitamente el valor predeterminado con -t stdio e incluir la bandera -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 — asegura los modos de red: En los modos SSE y HTTP transmisible, el contenedor enlaza una dirección no loopback (0.0.0.0:8000). Sin un token de llamador, el servidor se inicia pero registra un error de seguridad (en el nivel de registro error, por lo que no está oculto por --log-level; y se negará a iniciar en una futura versión principal). Establece MCP_GRAFANA_SERVER_TOKEN para requerir un Authorization: Bearer <token> de los clientes (recomendado). El modo STDIO no se ve afectado. Consulta Autenticación del Llamador.
  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 la bandera -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 HTTP Transmisible: En este modo, el servidor opera como un proceso independiente que puede manejar múltiples conexiones de clientes. Debes exponer el puerto 8000 usando la bandera -p: Para este modo debes 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 HTTP transmisible HTTPS 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: Descarga la última versión de mcp-grafana desde la página de versiones y colócala en tu $PATH.
- Compilar desde el código fuente: Si tienes un kit de herramientas Go instalado, 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 gráfico 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
```

Agrega la configuración del servidor a tu archivo de configuración del 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 anula 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 cuando se usa la imagen Docker sin anular 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 transmisible HTTPS con certificados TLS del servidor:

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

Modo de Depuración

Puedes habilitar el modo de depuración para el transporte de Grafana agregando la bandera -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, actualiza tu configuración de la siguiente manera:

Si usas 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 usas 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 tu instancia de Grafana está detrás de mTLS o requiere certificados TLS personalizados, puedes 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, úsalo 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 Prometheus
Clientes de fuentes de datos Loki
Clientes de gestión de incidentes
Clientes de investigación Sift
Clientes de alertas
Clientes 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

Con solo certificado CA personalizado:

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

Uso programático:

Si estás usando esta biblioteca programáticamente, también puedes 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), pre-valida 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 HTTP Transmisible)

Cuando usas el transporte HTTP transmisible (-t streamable-http), puedes configurar el servidor MCP para servir HTTPS en lugar de HTTP. Esto es útil cuando necesitas asegurar la conexión entre tu cliente MCP y el propio servidor.

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

--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: Estas banderas son completamente separadas de las banderas TLS del cliente documentadas anteriormente. Las banderas TLS del cliente configuran cómo el servidor MCP se conecta a Grafana, mientras que estas banderas TLS del servidor configuran cómo los clientes se conectan al servidor MCP cuando usan el transporte HTTP transmisible.

Ejemplo con servidor HTTP transmisible 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 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

Punto Final de Verificación de Salud

Cuando usas los transportes SSE (-t sse) o HTTP transmisible (-t streamable-http), el servidor MCP expone un punto final de verificación de salud en /healthz. Este punto final puede ser utilizado por balanceadores de carga, sistemas de monitoreo o plataformas de orquestación para verificar que el servidor está ejecutándose y aceptando conexiones.

Punto final: 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

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

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

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

Estadísticas de Uso Anónimas

El servidor puede reportar estadísticas de uso anónimas sobre sí mismo a Grafana Labs: qué herramientas fueron llamadas, cuántas de esas llamadas fallaron y cómo está configurado el servidor. Un reporte cubre un proceso del servidor — no un usuario y no una conversación — y se envía cada 4 horas además de una vez al apagarse. El reporte está deshabilitado por defecto en esta versión — el endpoint receptor aún no está activo — y una versión posterior cambiará el valor predeterminado a habilitado con la misma opción de exclusión.

Los argumentos de las herramientas, nombres de recursos, consultas, líneas de registro, mensajes de error y credenciales nunca se envían. Las banderas se registran solo por nombre, nunca por valor, y la instancia de Grafana se describe solo como cloud o self_hosted — nunca por URL, nombre de host, slug de stack u organización. Nada es por usuario, por sesión o por cliente: no hay identificador de sesión en el cable y no hay forma de atribuir una llamada de herramienta a un cliente particular.

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

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

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

DO_NOT_TRACK=1 también deshabilita el reporte, siguiendo la convención DO_NOT_TRACK entre herramientas. Solo 1 tiene efecto, solo puede deshabilitar, y tanto --usage-stats como GRAFANA_USAGE_STATS lo anulan, por lo que un host que lo establece globalmente aún puede optar por reactivar un servidor.

GRAFANA_USAGE_STATS_ENDPOINT cambia el destino. No es una opción de exclusión.

Para la lista completa de campos, qué nunca se envía, cómo leer los datos y sus limitaciones, consulte Estadísticas de uso anónimas.

Observabilidad

El servidor MCP admite métricas de Prometheus, trazado distribuido de OpenTelemetry y exportación de registros de OpenTelemetry, siguiendo las convenciones semánticas de OTel MCP. El trazado 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 independientemente.

Métricas

Al usar los transportes SSE o HTTP transmisible, habilite las métricas de Prometheus con la bandera --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 las 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 las sesiones de cliente MCP (etiquetas: `network_transport`, `mcp_protocol_version`)
`http_server_request_duration_seconds`	Histograma	Duración de las solicitudes del servidor HTTP (de otelhttp)

Nota: Las métricas solo están disponibles al usar los transportes SSE o HTTP transmisible. No están disponibles con el transporte stdio.

Cuando la protección de costos de Loki (--loki-guardrail-mode) está habilitada, cuatro contadores más registran sus decisiones:

Métrica	Tipo	Descripción
`mcp_loki_guardrail_admitted_total`	Contador	Consultas que pasaron todas las verificaciones habilitadas (etiquetas: `backend`)
`mcp_loki_guardrail_would_block_total`	Contador	Consultas que fallaron una verificación en modo `shadow` y se ejecutaron de todos modos (etiquetas: `backend`, `reason`)
`mcp_loki_guardrail_blocked_total`	Contador	Consultas rechazadas en modo `enforce` (etiquetas: `backend`, `reason`)
`mcp_loki_guardrail_fail_open_total`	Contador	Consultas que la protección no pudo evaluar y admitió (etiquetas: `backend`, `cause`)

reason es uno de selector, range, bytes; cause es uno de unparseable, estimate_failed; backend es uno de loki, victorialogs, unknown. Una consulta que activa varias verificaciones se cuenta una vez, etiquetada con la verificación que se ejecutó primero (selector, luego range, luego bytes), por lo que los cuatro contadores dividen la población protegida. Consulte Observabilidad para saber cómo leerlos durante un despliegue de shadow → enforce.

Los integradores de bibliotecas deben establecer GrafanaConfig.MeterProvider (la contraparte de métricas de GrafanaConfig.Logger): la protección se ejecuta dentro de un manejador de herramientas, por lo que no tiene una opción de constructor, y un proceso que instala un MeterProvider global noop de lo contrario descartaría cada registro.

Registro de solicitudes lentas

La bandera --slow-request-threshold emite un evento de registro estructurado cada vez que una solicitud MCP (invocación de herramienta, lista, lectura de recurso, etc.) supera la duración dada. Es útil para diagnosticar consultas y llamadas de 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:

Atributo	Descripción
`mcp.method`	El método MCP (por ejemplo, `tools/call`, `tools/list`, `resources/read`)
`duration`	Duración de 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 deshabilita por completo. Las herramientas proxy fluyen a través de tools/call y se cubren automáticamente.

Trazado

El trazado distribuido se configura mediante variables de entorno estándar de OTEL_* y funciona independientemente de la bandera --metrics. Cuando OTEL_EXPORTER_OTLP_ENDPOINT (o el OTEL_EXPORTER_OTLP_TRACES_ENDPOINT específico de señal) está establecido, el servidor exporta trazas 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 spans de llamadas de 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 traza W3C desde el campo _meta de las solicitudes de llamadas de herramientas.

Registros

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

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

Si usa el OTEL_EXPORTER_OTLP_ENDPOINT genérico pero desea deshabilitar la exportación de registros (por ejemplo, su backend no admite el 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 stderr no cambia cuando el registro OTLP está habilitado; puede continuar confiando en los registros de contenedores o canalizar 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 OTEL_EXPORTER_OTLP_ENDPOINT genérico) al endpoint gRPC remoto y proporcionando autenticación a través de OTEL_EXPORTER_OTLP_LOGS_HEADERS (o OTEL_EXPORTER_OTLP_HEADERS), reflejando el ejemplo de trazado anterior. Un colector OTel local es opcional — útil para fan-out, agrupación o enrutamiento multi-backend, pero no requerido.

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 no es accesible, 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 búfer sin pérdidas durante interrupciones.

Los registros también se exportan bajo el transporte stdio, lo que facilita centralizar 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

Aplicación de consultas de Loki

--loki-enforced-matchers permite a un operador restringir qué flujos de registros de Loki el servidor puede leer, aplicando un conjunto fijo de coincidencias de etiquetas LogQL en cada consulta nativa de Loki que el servidor emite. Esto es útil cuando un datasource contiene flujos que no deben exponerse (por ejemplo, registros que pueden llevar información sensible) pero no puede restringir el acceso en la capa de Grafana o Loki (OSS no tiene control de acceso por etiquetas por datasource o por usuario).

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

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

Cómo funciona:

Las coincidencias se analizan una vez al inicio (entrada inválida aborta el servidor) y se agregan a cada selector de flujo en cada consulta. Debido a que Loki aplica coincidencias dentro de un selector, una consulta de usuario solo puede estrechar los resultados dentro de los límites aplicados — nunca puede ampliarlos. Un selector de usuario que entre en conflicto con la política (por ejemplo, solicitar {namespace="vault"} bajo una exclusión) simplemente devuelve nada.
Cubre query_loki_logs, query_loki_stats, query_loki_patterns, list_loki_label_names y list_loki_label_values.
Falla cerrado: cualquier consulta que no se pueda analizar se rechaza en lugar de enviarse sin filtrar.
Los datasources de VictoriaLogs usan LogsQL, que no se puede reescribir de manera segura, por lo que se rechazan por completo mientras la aplicación esté habilitada.
Las coincidencias puramente negativas no pueden delimitar los endpoints de enumeración de etiquetas (Loki rechaza un selector independiente sin coincidencia positiva). Controle ese caso límite con --loki-label-enumeration-fallback (reject por defecto, o unfiltered para permitir la enumeración sin alcance de metadatos de etiquetas — las líneas de registro nunca se exponen). Las coincidencias positivas/de lista blanca no se ven afectadas.

[!IMPORTANTE] La aplicación solo se aplica a las herramientas de consulta de Loki. Otras herramientas pueden acceder a los datos de registros de Loki a través de rutas que nunca tocan el backend aplicado, por lo que para que la restricción realmente se mantenga, también debe deshabilitarlas:

--disable-api — grafana_api_request puede consultar el proxy del datasource de Loki directamente (omisión completa).

--disable-rendering — get_panel_image renderiza paneles de Loki en el servidor, produciendo imágenes con líneas de registro sin restricciones.

--disable-sift — Las investigaciones de Sift analizan registros de Loki en el servidor en todos los flujos.

--disable-assistant — ask_assistant delega a Grafana Assistant, que lee Loki en el servidor en todos los flujos. Solo se registra cuando las herramientas de escritura están habilitadas, por lo que --disable-write también lo cierra.

El servidor registra una advertencia al inicio nombrando cada una de estas que aún está habilitada. run_panel_query es seguro (reutiliza la ruta de consulta aplicada). Las herramientas de Tempo consultan trazas, no registros de Loki, por lo que no son una omisión. Las instantáneas de paneles (--disable-snapshot) también pueden incrustar datos de paneles de registros capturados fuera de la aplicación.

Solución de problemas

Compatibilidad de versiones de Grafana

Si encuentra el siguiente error al usar herramientas relacionadas con datasources:

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 9.0. El endpoint de API /datasources/uid/{uid} se introdujo en Grafana 9.0, y las operaciones de datasource 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! Lea CONTRIBUTING.md primero — cubre qué pertenece a este servidor y cómo proponerlo. Si estás añadiendo una nueva herramienta, por favor abre una propuesta de herramienta antes de escribir el código. Cada herramienta habilitada por defecto se envía al modelo en cada solicitud de cada usuario, por lo que preferimos discutir la idea antes que rechazar una solicitud de extracción terminada. Las correcciones de errores, documentación, pruebas y nuevos parámetros en herramientas existentes no necesitan propuesta — solo envía un PR.

Este proyecto está escrito en Go. Instala Go siguiendo las instrucciones para tu plataforma.

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

make run

Para ejecutar el servidor localmente en modo SSE, usa:

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

También puedes 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 usa el modo SSE por defecto. Para construir la imagen, usa:

make build-image

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

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

Si necesitas ejecutarla en modo STDIO en su lugar, anula la configuración del 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 puedes 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 una 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ás configurar tu 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; puedes iniciar una con Docker Compose:

docker-compose up -d

Las pruebas de integración se pueden ejecutar con:

make test-all

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

Linting

Para hacer lint del código, ejecuta:

make lint

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

make lint-jsonschema

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

Licencia

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