Introducción Detallada al Proyecto Grafana MCP Server

Resumen del Proyecto

Grafana MCP Server es un servidor basado en el Protocolo de Contexto de Modelo (Model Context Protocol, MCP), diseñado específicamente para integrarse con instancias de Grafana y su ecosistema circundante. Este proyecto proporciona a los agentes de IA (como Claude Desktop) la capacidad de acceder y operar varias funciones de Grafana.

Características y Funcionalidades Principales

Gestión de Paneles

• Buscar Paneles: Recupera y localiza rápidamente paneles específicos.
• Obtener Panel: Obtiene la configuración completa del panel a través de su UID.
• Actualizar/Crear Paneles: Modifica dinámicamente o crea nuevos paneles (teniendo en cuenta las limitaciones de la ventana de contexto).

Integración de Fuentes de Datos

• Gestión de Fuentes de Datos: Lista y obtiene información de las fuentes de datos.
• Soporte para Consultas de Múltiples Fuentes de Datos:
  • Prometheus: Ejecuta consultas PromQL para obtener datos de métricas.
  • Loki: Ejecuta consultas LogQL para recuperar datos de registro.
  • Tempo: Consulta de datos de rastreo distribuido.
  • Pyroscope: Consulta de datos de análisis de rendimiento.

Consulta de Metadatos

• Metadatos de Prometheus: Obtiene metadatos de métricas, nombres de métricas, nombres de etiquetas y valores de etiquetas.
• Metadatos de Loki: Obtiene nombres de etiquetas de registro, valores de etiquetas e información estadística.

Gestión de Eventos y Alertas

• Gestión de Eventos: Busca, crea, actualiza y cierra eventos.
• Reglas de Alerta: Lista y obtiene información de las reglas de alerta, obtiene el estado de las alertas.
• Gestión de Puntos de Contacto: Lista, crea y modifica los puntos de contacto de alerta.

Integración con Grafana OnCall

• Gestión de Horarios: Lista y gestiona los planes de guardia.
• Información de Guardia: Obtiene detalles de la guardia y el usuario actual de guardia.
• Gestión de Equipos y Usuarios: Gestiona equipos e información de usuarios.
• Gestión de Grupos de Alerta: Lista los grupos de alerta.

Funcionalidad de Investigación Sift

• Investigación Inteligente: Inicia investigaciones Sift y visualiza los resultados.
• Gestión de Investigaciones: Crea, lista y obtiene información de las investigaciones.
• Funcionalidad de Análisis: Obtiene resultados del análisis de la investigación.
• Reconocimiento de Patrones de Error: Busca patrones de error en los registros.
• Análisis de Rendimiento: Identifica solicitudes lentas.

Configuración de Herramientas

Este proyecto ofrece opciones de configuración de herramientas flexibles, permitiéndote habilitar o deshabilitar categorías de funciones específicas:

Nombre de la Herramienta	Categoría	Descripción
search_dashboards	Search	Buscar paneles
get_dashboard_by_uid	Dashboard	Obtener panel por UID
update_dashboard	Dashboard	Actualizar o crear un nuevo panel
list_datasources	Datasources	Listar fuentes de datos
query_prometheus	Prometheus	Ejecutar consulta Prometheus
query_loki_logs	Loki	Consultar y recuperar registros
list_incidents	Incident	Listar eventos
list_alert_rules	Alerting	Listar reglas de alerta
list_oncall_schedules	OnCall	Listar planes de guardia de OnCall
find_error_pattern_logs	Sift	Buscar patrones de error

Utiliza el flag --disable-<categoría> para deshabilitar categorías de herramientas específicas. Por ejemplo, usa --disable-oncall para deshabilitar las herramientas relacionadas con OnCall.

Instalación y Configuración

Métodos de Instalación

1. Imagen de Docker

docker pull mcp/grafana
docker run -p 8000:8000 -e GRAFANA_URL=http://localhost:3000 -e GRAFANA_API_KEY=<your_token> mcp/grafana

2. Descargar Archivo Binario

Descarga la última versión desde la página de releases y colócala en el directorio $PATH.

3. Compilación desde el Código Fuente

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

Ajustes de Configuración

Prerrequisitos

1. Crea una cuenta de servicio en Grafana y asigna los permisos suficientes.
2. Genera un token de cuenta de servicio.

Configuración de Claude Desktop

Usando el archivo binario:

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

Usando Docker:

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

Modo de Depuración

Habilita el modo de depuración añadiendo el flag -debug, que proporcionará registros detallados de las peticiones y respuestas HTTP:

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

Desarrollo y Pruebas

Configuración del Entorno de Desarrollo

# Ejecutar el servidor
make run

# Construir la imagen de Docker
make build-image

# Ejecutar el contenedor de Docker
docker run -it --rm -p 8000:8000 mcp-grafana:latest

Tipos de Pruebas

Pruebas Unitarias

make test-unit
# O
make test

Pruebas de Integración

# Necesita que el contenedor de Docker esté en ejecución
make test-integration

Pruebas en la Nube

# Necesita una instancia de Grafana en la nube y credenciales
make test-cloud

Pruebas Completas

# Inicia una instancia local de Grafana
docker-compose up -d

# Ejecuta todas las pruebas
make test-all

Calidad del Código

Revisión del Código

make lint

Revisión del Esquema JSON

Este proyecto incluye un linter personalizado para revisar comas sin escape en las etiquetas de estructura jsonschema:

make lint-jsonschema

Arquitectura Técnica

• Lenguaje de Programación: Go
• Protocolo: Model Context Protocol (MCP)
• Método de Comunicación: stdin/stdout o SSE (Server-Sent Events)
• Clientes Soportados: Claude Desktop y otros clientes compatibles con MCP

Casos de Uso

1. Monitorización Impulsada por IA: Permite a los agentes de IA consultar y analizar de forma inteligente los datos de monitorización.
2. Operaciones Automatizadas: Automatiza la creación y gestión de paneles y reglas de alerta a través de la IA.
3. Respuesta Inteligente a Incidentes: Utiliza la IA para analizar registros y métricas, localizando y resolviendo problemas rápidamente.
4. Perspectivas de Datos: Permite a la IA ayudar a extraer información valiosa de datos de monitorización complejos.

Este proyecto representa una nueva tendencia en la integración de la IA con las herramientas de monitorización tradicionales, proporcionando a los desarrolladores un puente poderoso que conecta asistentes de inteligencia artificial y el ecosistema de Grafana.