Grafana

Accede a recursos de Grafana como 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 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 soportar streamable-http
  • Se añadió la dependencia: github.com/DataDog/zstd

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.

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 funciones futuras.

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: Úsalo con precaución debido a las limitaciones de la ventana de contexto; consulta el problema #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: Visualiza todas las fuentes de datos configuradas y recupera información detallada sobre cada una.
    • Tipos de fuentes de datos compatibles: Prometheus, Loki, QuestDB, Athena.

Consultas de 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 de 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: Visualiza las reglas de alerta y sus estados (disparada/normal/error/etc.) en Grafana.
  • Listar puntos de contacto: Visualiza los puntos de contacto de notificación configurados en Grafana.

Grafana OnCall

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

Administración

  • Listar equipos: Visualiza 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 deseas 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 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 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 una matriz de objetos JSON, uno por fila.
query_athena_sqlAthenaFuente de datos Athena: Ejecuta SQL arbitrario y devuelve los resultados como una matriz 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 precompilada 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 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=<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 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=<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, debes 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 anula el modo SSE predeterminado 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 predeterminado al usar la imagen de 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"
    }
  }
}

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 anular el modo SSE predeterminado en la imagen de Docker.

Desarrollo

¡Las contribuciones son bienvenidas! Abre un problema o envía una solicitud de extracción 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), 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 está configurado por defecto en modo SSE. 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 ejecutarlo 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:

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

También puedes ejecutar las pruebas unitarias con:

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

Las pruebas de integración más completas requerirán que una instancia de Grafana se esté ejecutando 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, agrega 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 la truncación silenciosa. 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.