Bifurcado deGrafana MCP server

Este repositorio es una bifurcación del servidor Grafana MCP original.
Incluye modificaciones personalizadas listadas a continuación.

Cambios desde la versión original

• Añadido soporte para una nueva herramienta: QuestDB
  • Introducida la bandera questdb para activar/desactivar
  • Añadido tools/questdb.go que implementa la lógica de consulta de QuestDB
• Añadido soporte para una nueva herramienta: Athena
  • Introducida la bandera athena para activar/desactivar
  • Añadido tools/athena. go para implementar la lógica de consulta de Athena
• Ampliadas las opciones de transporte para soportar streamable-http
• Añadida dependencia: github.com/DataDog/zstd

Servidor MCP de Grafana

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

Esto proporciona acceso a su instancia Grafana y el ecosistema circundante.

Características

Las siguientes características están actualmente disponibles en el servidor MCP. Esta lista es sólo para fines informativos y no representa una hoja de ruta o compromiso con las características futuras.

Cuadros de mando

• Búsqueda de cuadros de mando: Buscar cuadros de mando por título u otros metadatos
• Obtener cuadro de mando por UID: Recuperar todos los detalles del cuadro de mando utilizando su identificador único
• Actualizar o crear un cuadro de mando: Modificar cuadros de mando existentes o crear nuevos. Nota: Utilícelo con precaución debido a las limitaciones de la ventana contextual; consulte el problema nº 101
• Obtener consultas del panel e información de la fuente de datos: Obtenga el título, la cadena de consulta y la información de la fuente de datos (incluidos el UID y el tipo, si están disponibles) de cada panel de un cuadro de mando

Fuentes de datos

• Listar y obtener información de fuentes de datos: Ver todos los orígenes de datos configurados y recuperar información detallada sobre cada uno
  • Tipos de fuentes de datos compatibles: Prometheus, Loki, QuestDB, Athena.

Consulta de Prometheus

• Consulta de Prometheus: Ejecute consultas PromQL (admite consultas métricas instantáneas y de rango) contra fuentes de datos Prometheus.
• Consulta de metadatos de Prometheus: Recupere metadatos de métricas, nombres de métricas, nombres de etiquetas y valores de etiquetas de fuentes de datos de Prometheus.

Consulta de Loki

• Consulta de registros y métricas de Loki: Ejecute tanto consultas de registros como consultas de métricas utilizando LogQL contra fuentes de datos de Loki.
• Consulta de metadatos de Loki: Recupere nombres de etiquetas, valores de etiquetas y estadísticas de flujo de las fuentes de datos de Loki.

Incidentes

• Buscar, crear, actualizar y cerrar incidentes: Gestione incidentes en Grafana Incident, incluidas la búsqueda, la creación, la actualización y la resolución de incidentes.

Investigaciones de Sift

• Cree investigaciones de Sift: Inicie una nueva investigación de Sift para analizar registros o rastros.
• Listar investigaciones de Sift: Recupere una lista de investigaciones de Sift, con soporte para un parámetro de límite.
• Obtener investigación de Sift: Recuperar detalles de una investigación de Sift específica por su UUID.
• Obtener análisis de Sift: Recupera un análisis específico de una investigación de Sift.
• Encontrar patrones de error en los registros: Detecte patrones de error elevados en los registros de Loki mediante Sift.
• Buscar solicitudes lentas: Detecte solicitudes lentas mediante Sift (Tempo).

Alertas

• Listar y obtener información sobre reglas de alerta: Ver reglas de alerta y sus estados (disparando/normal/error/etc.) en Grafana.
• Listar puntos de contacto: Ver los puntos de contacto de notificación configurados en Grafana.

Grafana de guardia

• Listar y gestionar horarios: Ver y gestionar los horarios de guardia en Grafana OnCall.
• Obtener detalles del turno: Recuperar información detallada sobre turnos de guardia específicos.
• Obtener usuarios de guardia actuales: Ver qué usuarios están actualmente de guardia para un horario.
• Listar equipos y usuarios: Ver todos los equipos y usuarios de guardia.

Admin

• Listar equipos: Ver todos los equipos configurados en Grafana.

La lista de herramientas es configurable, por lo que puede elegir qué herramientas desea poner a disposición del cliente MCP. Esto resulta útil si no utiliza determinadas funciones o si no desea ocupar demasiado espacio en la ventana contextual. Para desactivar una categoría de herramientas, utilice el indicador --disable-<category> al iniciar el servidor. Por ejemplo, para desactivar las herramientas OnCall, utilice --disable-oncall.

Herramientas

Uso

1. Cree una cuenta de servicio en Grafana con permisos suficientes para utilizar las herramientas que desee, genere un token de cuenta de servicio y cópielo en el portapapeles para utilizarlo en el archivo de configuración. Siga la documentación de Grafana para obtener más detalles.

2. Tienes varias opciones para instalar mcp-grafana:

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

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

     1. Modo STDIO: Para el modo stdio debe anular explícitamente el valor predeterminado con -t stdio e incluir la bandera -i para mantener stdin abierto:

     docker pull mcp/grafana docker run --rm -i -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<su token de cuenta de servicio> mcp/grafana -t stdio

     2. Modo SSE: En este modo, el servidor se ejecuta como un servidor HTTP al que se conectan los clientes. Debe exponer el puerto 8000 utilizando la bandera -p:

     docker pull mcp/grafana docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<su token de cuenta de servicio> mcp/grafana

     3. Modo HTTP Streamable: En este modo, el servidor funciona como un proceso independiente que puede manejar múltiples conexiones de clientes. Debe exponer el puerto 8000 usando la bandera -p: Para este modo debe anular explícitamente el valor predeterminado con -t streamable-http

     docker pull mcp/grafana docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<su token de cuenta de servicio> mcp/grafana -t streamable-http

   • Descargar binario: Descargue la última versión de mcp-grafana de la página de versiones y colóquela en su $PATH.

   • Construir desde el código fuente: Si tiene instalada una cadena de herramientas Go, también puede compilarlo e instalarlo desde el código fuente, utilizando la variable de entorno GOBIN para especificar el directorio donde debe instalarse el binario. También debe estar en su PATH.

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

3. Añada la configuración del servidor a su archivo de configuración del cliente. Por ejemplo, para Claude Desktop:

   Si utiliza el binario:

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

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

Si utiliza Docker:

{ "mcpServers": { "grafana": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "GRAFANA_URL", "-e", "GRAFANA_API_KEY", "mcp/grafana", "-t", "stdio" ], "env": { "GRAFANA_URL": "http://localhost:3000", "GRAFANA_API_KEY": "<su token de cuenta de servicio>" } } }

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

Usando VSCode con un servidor MCP remoto

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

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

Modo depuración

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

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

Si utiliza el binario:

{ "mcpServers": { "grafana": { "command": "mcp-grafana", "args": ["-debug"], "env": { "GRAFANA_URL": "http://localhost:3000", "GRAFANA_API_KEY": "<su token de cuenta de servicio>" } } }

Si se utiliza Docker:

{ "mcpServers": { "grafana": { "command": "docker", "args": [ "run", "--rm", "-i", "-e", "GRAFANA_URL", "-e", "GRAFANA_API_KEY", "mcp/grafana", "-t", "stdio", "-debug" ], "env": { "GRAFANA_URL": "http://localhost:3000", "GRAFANA_API_KEY": "<su token de cuenta de servicio>" } } }

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.

Desarrollo

¡Las contribuciones son bienvenidas! Por favor, abre un issue o envía un pull request si tienes alguna sugerencia o mejora.

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), utilice

make run

Para ejecutar el servidor localmente en modo SSE, utilice:

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

También puede ejecutar el servidor utilizando el transporte SSE dentro de una imagen Docker personalizada. Al igual que la imagen Docker publicada, el punto de entrada de esta imagen personalizada está predeterminado en modo SSE. Para construir la imagen, utilice

make build-image

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

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

Si necesitas ejecutarla en modo STDIO, anula la configuración de transporte:

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

Pruebas de

Hay tres tipos de pruebas disponibles:

1. Pruebas unitarias (no requiere dependencias externas):

make test-unit

También puede ejecutar pruebas unitarias con:

make test

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

make test-integration

3. Cloud Tests (requiere una instancia de Grafana en la nube y credenciales):

make test-cloud

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

Las pruebas de integración más completas requerirán una instancia de Grafana que se ejecute localmente en el puerto 3000; puedes iniciar una con Docker Compose:

docker-compose up -d

Las pruebas de integración pueden ejecutarse con

make test-all

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

Desagregando

Para limpiar el código, ejecuta

make lint

Esto incluye un linter personalizado que comprueba si hay comas no escapadas en las etiquetas struct de jsonschema. Las comas en los campos de descripción deben ser escapadas con \\ , para evitar el truncamiento silencioso. Puede ejecutar sólo este linter con

make lint-jsonschema

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

Licencia

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