Grafana

Accede y gestiona recursos de Grafana, incluidos paneles, fuentes de datos, Prometheus, Loki y alertas.

GitHubPrueba este MCPPatrocinado

Documentación

Bifurcado de Servidor MCP de Grafana

Este repositorio es una bifurcación del servidor MCP original de Grafana.
Incluye las modificaciones personalizadas que se enumeran a continuación.

Cambios respecto al upstream

  • Se añadió soporte para una nueva herramienta: QuestDB
    • Se introdujo la bandera questdb para habilitar/deshabilitar
    • Se añadió tools/questdb.go que implementa la lógica de consulta de QuestDB
  • Se añadió soporte para una nueva herramienta: Athena
    • Se introdujo la bandera athena para habilitar/deshabilitar
    • Se añadió tools/athena.go que implementa la lógica de consulta de Athena
  • Se ampliaron las opciones de transporte para admitir streamable-http
  • Se añadió la dependencia: github.com/DataDog/zstd

Servidor MCP de Grafana

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

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

Características

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

Paneles de control

  • Buscar paneles de control: Encuentra paneles de control por título u otros metadatos
  • Obtener panel de control por UID: Recupera los detalles completos del panel de control usando su identificador único
  • Actualizar o crear un panel de control: Modifica paneles de control existentes o crea nuevos. Nota: Usar con precaución debido a las limitaciones de la ventana de contexto; ver issue #101
  • 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

Fuentes de datos

  • Listar y obtener información de fuentes de datos: Ver todas las fuentes de datos configuradas y recuperar información detallada sobre cada una.
    • Tipos de fuentes de datos admitidos: Prometheus, Loki, QuestDB, Athena.

Consultas a Prometheus

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

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.

Incidentes

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

Investigaciones de Sift

  • Crear investigaciones de Sift: Inicia una nueva investigación de Sift para analizar registros o trazas.
  • 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 los 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 registros: Detecta patrones de error elevados en registros de Loki usando Sift.
  • Encontrar solicitudes lentas: Detecta solicitudes lentas usando Sift (Tempo).

Alertas

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

Grafana OnCall

  • Listar y gestionar horarios: Ver y gestionar 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: Ver qué usuarios están actualmente de guardia para un horario.
  • Listar equipos y usuarios: Ver todos los equipos y usuarios de OnCall.

Administración

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

La lista de herramientas es configurable, por lo que puedes elegir qué herramientas deseas poner a disposición del cliente MCP. Esto es útil si no usas cierta funcionalidad o si no quieres ocupar demasiado espacio en la ventana de contexto. Para deshabilitar una categoría de herramientas, usa la bandera --disable-<category> al iniciar el servidor. Por ejemplo, para deshabilitar las herramientas de OnCall, usa --disable-oncall.

Herramientas

HerramientaCategoríaDescripción
list_teamsAdministraciónListar todos los equipos
search_dashboardsBúsquedaBuscar paneles de control
get_dashboard_by_uidPanel de controlObtener un panel de control por UID
update_dashboardPanel de controlActualizar o crear un nuevo panel de control
get_dashboard_panel_queriesPanel de controlObtener título del panel, consultas, UID de fuente de datos y tipo de un panel de control
list_datasourcesFuentes de datosListar fuentes de datos
get_datasource_by_uidFuentes de datosObtener una fuente de datos por UID
get_datasource_by_nameFuentes de datosObtener una fuente de datos por nombre
query_prometheusPrometheusEjecutar una consulta contra una fuente de datos de Prometheus
list_prometheus_metric_metadataPrometheusListar metadatos de métricas
list_prometheus_metric_namesPrometheusListar nombres de métricas disponibles
list_prometheus_label_namesPrometheusListar nombres de etiquetas que coinciden con un selector
list_prometheus_label_valuesPrometheusListar valores para una etiqueta específica
list_incidentsIncidenteListar incidentes en Grafana Incident
create_incidentIncidenteCrear un incidente en Grafana Incident
add_activity_to_incidentIncidenteAñadir un elemento de actividad a un incidente en Grafana Incident
resolve_incidentIncidenteResolver un incidente en Grafana Incident
query_loki_logsLokiConsultar y recuperar registros usando LogQL (consultas de registros o métricas)
list_loki_label_namesLokiListar todos los nombres de etiquetas disponibles en los registros
list_loki_label_valuesLokiListar valores para una etiqueta de registro específica
query_loki_statsLokiObtener estadísticas sobre flujos de registros
list_alert_rulesAlertasListar reglas de alerta
get_alert_rule_by_uidAlertasObtener regla de alerta por UID
list_oncall_schedulesOnCallListar horarios de Grafana OnCall
get_oncall_shiftOnCallObtener detalles de un turno de OnCall específico
get_current_oncall_usersOnCallObtener usuarios actualmente de guardia para un horario específico
list_oncall_teamsOnCallListar equipos de Grafana OnCall
list_oncall_usersOnCallListar usuarios de Grafana OnCall
get_investigationSiftRecuperar una investigación de Sift existente por su UUID
get_analysisSiftRecuperar un análisis específico de una investigación de Sift
list_investigationsSiftRecuperar una lista de investigaciones de Sift con un límite opcional
find_error_pattern_logsSiftEncuentra patrones de error elevados en registros de Loki.
find_slow_requestsSiftEncuentra solicitudes lentas de las fuentes de datos de tempo relevantes.
list_pyroscope_label_namesPyroscopeListar nombres de etiquetas que coinciden con un selector
list_pyroscope_label_valuesPyroscopeListar valores de etiquetas que coinciden con un selector para un nombre de etiqueta
list_pyroscope_profile_typesPyroscopeListar tipos de perfil disponibles
fetch_pyroscope_profilePyroscopeObtiene un perfil en formato DOT para análisis
query_questdb_sqlQuestDBFuente de datos QuestDB: Ejecuta SQL arbitrario y devuelve los resultados como un array de objetos JSON, uno por fila.
query_athena_sqlAthenaFuente de datos Athena: Ejecuta SQL arbitrario y devuelve los resultados como un array de objetos JSON, uno por fila.

Uso

  1. Crea una cuenta de servicio en Grafana con permisos suficientes para usar las herramientas que deseas usar, genera un token de cuenta de servicio y cópialo al portapapeles para usarlo en el archivo de configuración. Sigue la documentación de Grafana para más detalles.

  2. Tienes varias opciones para instalar mcp-grafana:

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

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

      1. Modo STDIO: Para el modo stdio debes sobrescribir explícitamente el valor por defecto 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=<your service account token> mcp/grafana -t stdio
      1. Modo SSE: En este modo, el servidor se ejecuta como un servidor HTTP al que los clientes se conectan. Debes exponer el puerto 8000 usando la bandera -p:
      docker pull mcp/grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your service account token> mcp/grafana
      1. Modo HTTP Streamable: 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 sobrescribir explícitamente el valor por defecto con -t streamable-http
      docker pull mcp/grafana
docker run --rm -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your service account token> mcp/grafana -t streamable-http

    • 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 de 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

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

    Si usas 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 usas 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": "<your service account token>"
      }
    }
  }
}

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

Usando VSCode con servidor MCP remoto

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

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

Modo de depuración

Puedes habilitar el modo de depuración para el transporte de Grafana añadiendo 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",
        "GRAFANA_API_KEY": "<your service account token>"
      }
    }
  }
}

Si usas 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": "<your service account token>"
      }
    }
  }
}

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

Desarrollo

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

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), use:

make run

Para ejecutar el servidor localmente en modo SSE, use:

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

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

make build-image

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

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

Si necesita ejecutarla en modo STDIO en su lugar, anule la configuración del transporte:

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

Pruebas

Hay tres tipos de pruebas disponibles:

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

También puede ejecutar pruebas unitarias con:

make test
  1. Pruebas de integración (requieren que los contenedores Docker estén en funcionamiento):
make test-integration
  1. Pruebas en la nube (requieren 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 el desarrollo local, necesitará configurar su propia instancia de Grafana Cloud y sus credenciales.

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

docker-compose up -d

Las pruebas de integración se pueden ejecutar con:

make test-all

Si está agregando más herramientas, agregue pruebas de integración para ellas. Las pruebas existentes deberían ser un buen punto de partida.

Linting

Para hacer lint del código, ejecute:

make lint

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

make lint-jsonschema

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

Licencia

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