grafana-mcp

Expone una parte de la API de Grafana como un servidor MCP (Model Context Protocol), centrado en la consulta de registros en lenguaje natural. El objetivo principal: decir "muéstrame los registros de error del servicio api en los últimos 30 minutos" y obtener las líneas de registro reales, sin tener que gestionar LogQL, etiquetas o UID de fuentes de datos manualmente.

Las fuentes de datos de registro, las etiquetas de Loki y el mapeo de un nombre de servicio a su fuente de datos/etiqueta de alojamiento se almacenan en caché en el disco, por lo que las llamadas repetidas omiten escaneos de etiquetas redundantes.

한국어 문서 / Korean README

Instalación y configuración

npx (no requiere instalación)

Añade lo siguiente a ~/.mcp.json.

{
  "mcpServers": {
    "grafana": {
      "command": "npx",
      "args": ["@seungje.jun/grafana-mcp"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

Construir desde el código fuente

git clone https://github.com/ninanung/grafana-mcp.git
cd grafana-mcp
npm install
npm run build

{
  "mcpServers": {
    "grafana": {
      "command": "node",
      "args": ["/path/to/grafana-mcp/dist/cli.js"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "GRAFANA_SERVICE_ACCOUNT_TOKEN": "glsa_xxx"
      }
    }
  }
}

Reinicia Claude Code para activar las herramientas MCP.

Autenticación

Se requiere una de las siguientes opciones. Se verifican en el orden que aparece a continuación: la primera que esté presente es la que se utiliza.

Todos los tokens de tipo bearer se envían como Authorization: Bearer <token>. Al servidor no le importa qué tipo de token sea, solo elige el que esté configurado.

Variables de entorno

Related MCP server: Log Analyzer MCP Server

Herramientas

Ejemplo de uso

Un flujo típico de lenguaje natural, orquestado por el cliente MCP:

1. Usuario: "Muéstrame los registros de error del servicio api en los últimos 30 minutos."

2. query_logs con service: "api", level: "error", time_from: "now-30m" → el servidor detecta automáticamente qué fuente de datos de Loki posee la etiqueta service="api" y ejecuta LogQL.

3. (Primera llamada) el mapeo de servicio → fuente de datos/etiqueta se guarda en la caché; las llamadas posteriores omiten el paso de detección.

4. Usuario: "Resume esos errores por patrón." → la misma llamada con output: "summarize" devuelve recuentos agrupados por patrón.

5. Usuario: "¿Qué otros servicios tenemos?" → list_services devuelve la lista completa de servicios.

Si el nombre del servicio tiene un error tipográfico, query_logs muestra coincidencias cercanas (p. ej., ¿Quisiste decir: checkout, checkout-api?).

Cómo funciona la detección automática

query_logs elige la fuente de datos y la etiqueta de destino por sí mismo:

1. Filtra todas las fuentes de datos hasta los tipos de registro (Loki/ES/CloudWatch/OpenSearch/Splunk).

2. Para cada fuente de datos de Loki, obtiene /loki/api/v1/labels y recorre los candidatos a etiquetas de servicio comunes (service, service_name, app, app_name, application, container, job) primero, luego cualquier etiqueta restante.

3. Para cada etiqueta candidata, obtiene sus valores y verifica si el nombre del service solicitado está en esa lista.

4. Si coincide exactamente un par (datasource, label), úsalo. Si coinciden varios, requiere datasource_uid para desambiguar. Si ninguno coincide, devuelve sugerencias de nombres cercanos.

5. El (service → ds_uid, label) resuelto se almacena en caché; refresh: true o refresh_log_cache fuerza la redetección.

La detección automática actualmente solo admite Loki. Para fuentes de datos de Elasticsearch / CloudWatch / Splunk, pasa datasource_uid y service_label explícitamente (y espera que los filtros específicos de LogQL no se apliquen).

Modos de salida

query_logs acepta output:

• raw (predeterminado): <ISO timestamp> <log line> — bueno para lectura directa en una terminal.

• summarize: agrupa líneas por patrón normalizado (números → N, UUIDs → UUID) con recuentos y una muestra por patrón. Úsalo cuando las líneas sean ruidosas o demasiadas.

• json: objetos estructurados { ts, line, labels } — para herramientas posteriores.

Caché

• Caché de registros: persistida en ~/.grafana-mcp/log-cache.json. Clasificada por la URL base de Grafana para que las instancias múltiples no colisionen.

• Cada categoría tiene su propio TTL (fuentes de datos / etiquetas / valores de etiqueta / resolución de servicio) — consulta la tabla de variables de entorno anterior.

• Una resolución de servicio en caché que falla más tarde (p. ej., la etiqueta fue renombrada) se invalida automáticamente para que la siguiente llamada vuelva a detectar.

• Usa get_log_cache para inspeccionar, refresh_log_cache para borrar, y export_log_cache / import_log_cache para compartir con compañeros de equipo.

Ubicación y restablecimiento de la caché

El archivo de caché es un documento JSON simple: seguro para inspeccionar, editar o respaldar manualmente.

Seguridad y restricciones

• Solo lectura: el servidor no expone ningún punto final que modifique el estado de Grafana. Sin CRUD de paneles/fuentes de datos, sin cambios de alertas.

• Registros Stdio: todos los registros van a stderr, manteniendo limpio el canal stdio de MCP.

• Omisión de TLS: GRAFANA_TLS_SKIP_VERIFY=true establece NODE_TLS_REJECT_UNAUTHORIZED=0 en todo el proceso. Úsalo solo para Grafana autofirmado en redes confiables.

• Sin registro de secretos: los tokens de autenticación nunca se escriben en los registros de auditoría.

Licencia

MIT