MCP Prometheus

Un completo servidor de Protocolo de Contexto de Modelo (MCP) para Prometheus, escrito en Go.

Proporciona acceso completo a sus métricas, consultas e información del sistema Prometheus a través de interfaces MCP estandarizadas, permitiendo a los asistentes de IA ejecutar consultas PromQL, descubrir métricas, explorar etiquetas y analizar su infraestructura de monitorización.

Características

ejecución de consultas

• Consultas instantáneas con marca de tiempo opcional y parámetros mejorados
• Consultas de rango con límites de tiempo, intervalos de paso y opciones de rendimiento
• Optimización de consultas con parámetros de tiempo de espera, límite y estadísticas
• Truncamiento de resultados con guía inteligente del usuario para grandes conjuntos de datos

descubrimiento de métricas

• Lista de todas las métricas disponibles con filtrado y selección basada en el tiempo
• Obtenga metadatos detallados para métricas específicas
• Exploración de métricas con opciones de filtrado mejoradas

🏷️ Descubrimiento de etiquetas y series

• Listar todos los nombres de etiquetas con filtrado y límites
• Obtenga valores de etiqueta para etiquetas específicas con filtrado avanzado
• Búsqueda de series mediante comparadores de etiquetas con límites temporales
• Coincidencia avanzada de etiquetas con selectores complejos

información sobre objetivos y sistemas

• Raspe la información del objetivo y el estado de salud
• Información de compilación y detalles de versión
• Información de tiempo de ejecución y estado del sistema
• Inspección de configuración y banderas
• Estadísticas TSDB e información de cardinalidad

alertas y reglas

• Supervisión de alertas activas
• Detección y estado de AlertManager
• Inspección de reglas de grabación y alerta

funciones avanzadas

• Consultas de ejemplos para la correlación de trazas
• Exploración de metadatos de destino
• Soporte multi-tenant con IDs de organización dinámicos
• Configuración dinámica del cliente por consulta

autenticación y transporte

• Múltiples métodos de autenticación (Basic, Bearer token)
• Cabeceras de organización multi-tenant (Cortex, Mimir, Thanos)
• Múltiples protocolos de transporte (stdio, SSE, HTTP)
• Distribución binaria multiplataforma

Instalación

Binarios precompilados

Descargue el último binario para su plataforma desde la página de versiones.

Desde el código fuente

git clone https://github.com/giantswarm/mcp-prometheus.git cd mcp-prometheus go build -o mcp-prometheus

Configuración

Configure el servidor MCP mediante variables de entorno (todas opcionales):

# Opcional: Configuración por defecto del servidor Prometheus export PROMETHEUS_URL=http://your-prometheus-server:9090 # Opcional: Credenciales de autenticación (elija una) # Para autenticación básica exportar PROMETHEUS_USERNAME=su_nombre_de_usuario exportar PROMETHEUS_PASSWORD=su_contraseña # Para autenticación de token de portador exportar PROMETHEUS_TOKEN=su_token # Opcional: ID de organización por defecto para configuraciones multi-tenant export PROMETHEUS_ORGID=your_organization_id

Configuración dinámica: Todas las herramientas MCP admiten los parámetros prometheus_url y org_id para la configuración por consulta, lo que le permite consultar múltiples instancias y organizaciones de Prometheus de forma dinámica.

Uso

Línea de comandos

Inicie el servidor con transporte stdio (por defecto):

./mcp-prometheus

Iniciar con transporte HTTP para clientes basados en web:

./mcp-prometheus serve --transport sse --http-addr :8080

Configuración del cliente MCP

Añada la configuración del servidor a su cliente MCP. Por ejemplo, con Claude Desktop:

{ "mcpServers": { "prometheus": { "command": "/ruta/a/mcp-prometheus", "args": ["serve"], "env": { "PROMETHEUS_URL": "http://your-prometheus-server:9090", "PROMETHEUS_ORGID": "your-default-org" } } }

Herramientas disponibles

🔍 Herramientas de ejecución de consultas

📊 Herramientas de descubrimiento de métricas

🏷️ Herramientas de descubrimiento de etiquetas y series

🎯 Herramientas de información sobre objetivos y sistemas

🚨 Herramientas de alertas y reglas

🔬 Herramientas avanzadas

parámetros mejorados

Parámetros de conexión (disponibles en todas las herramientas):

• prometheus_url: URL del servidor Prometheus (por ejemplo,'http://localhost:9090')
• org_id: ID de organización para configuraciones multi-tenant (por ejemplo, 'tenant-123')

Parámetros de mejora de consultas:

• timeout: Tiempo de espera de la consulta (por ejemplo, '30s', '1m', '5m')
• limit: número máximo de entradas devueltas
• stats: Incluir estadísticas de consulta ('all')
• lookback_delta: Delta de retroceso de la consulta (por ejemplo, '5m')
• unlimited: Establecer como "true" para una salida ilimitada (ADVERTENCIA: puede afectar al rendimiento)

Parámetros de filtrado de tiempo:

• start_time, end_time: Marcas de tiempo RFC3339 para el filtrado
• coincidencias: Matriz de comparadores de etiquetas (por ejemplo, ['{job="prometheus"}', '{__name__=~"http_.*"}'])

Ejemplo de uso

Ejecución de consulta básica

{ "consulta": "up", "prometheus_url": "http://prometheus:9090", "org_id": "production" }

Consulta mejorada con opciones de rendimiento

{ "query": "rate(http_requests_total[5m])", "prometheus_url": "http://prometheus:9090", "timeout": "30s", "limit": "100", "stats": "all" }

Consulta de rango con límites temporales

{ "consulta": "cpu_usage_percent", "start": "2025-01-27T00:00:00Z", "end": "2025-01-27T01:00:00Z", "step": "1m", "prometheus_url": "http://prometheus:9090" }

Descubrimiento de etiquetas con filtrado

{ "prometheus_url": "http://prometheus:9090", "matches": ["up{job="kubernetes-nodos"}"], "limit": "20" }

Series Discovery

{"coincidencias": ["{__name__=~\"http_.*\", job="api-server"}"], "prometheus_url": "http://prometheus:9090", "start_time": "2025-01-27T00:00:00Z", "limit": "50" }

Consulta multiinquilino

{ "consulta": "container_memory_usage_bytes", "prometheus_url": "http://cortex-gateway:8080/prometheus", "org_id": "equipo-plataforma" }

Optimización del resultado de las consultas

El servidor MCP incluye una gestión inteligente de los resultados de las consultas:

• Truncamiento automático para resultados > 50k caracteres
• Guía del usuario para la optimización de consultas cuando los resultados son extensos
• Consejos de rendimiento que incluyen funciones de agregación y filtrado
• Opción de salida ilimitada con advertencias de rendimiento

Ejemplo de mensaje de truncamiento:

⚠️ RESULTADO TRUNCADO: La consulta devolvió un resultado muy grande (>50k caracteres). 💡 Para optimizar la consulta y obtener menos salida, considere: - Añadir filtros de etiquetas más específicos: {app="specific-app", namespace="specific-ns"} - Utilizar funciones de agregación: sum(), avg(), count(), etc. - Utilizar topk() o bottomk() para obtener sólo los N resultados superiores/inferiores 🔧 Para obtener el resultado completo sin truncar, añada "unlimited": "true" a los parámetros de consulta

Opciones de transporte

El servidor soporta múltiples protocolos de transporte:

stdio (por defecto)

./mcp-prometheus serve --transport stdio

SSE (Eventos enviados por el servidor)

./mcp-prometheus serve --transport sse --http-addr :8080

Streamable HTTP

./mcp-prometheus serve --transport streamable-http --http-addr :8080

Desarrollo

Arquitectura

El servidor sigue una arquitectura moderna y DRY:

• Registro modular de herramientas con reutilización de parámetros
• Creación dinámica de clientes para soporte multi-instancia
• Gestión de errores y validación de parámetroscentralizadas
• Funciones auxiliares para reducir la repetición de código en un 90%

Estructura del proyecto

mcp-prometheus/ ├── cmd/ # Comandos CLI e info de versión ├── internal/ │ ├── server/ # Contexto y configuración del servidor │ └── tools/prometheus/ # 18 herramientas MCP completas ├── main.go # Punto de entrada de la aplicación ├── go.mod # Dependencias de Go └── README.md # Esta documentación

Mejoras en la calidad del código

• 500+ líneas reducidas a ~85 líneas en el registro principal
• Eliminadas 255+ líneas de boilerplate redundante
• Funciones de ayuda de parámetros para definiciones de parámetros DRY
• Gestión centralizada de clientes con configuración dinámica
• Gestión de errores coherente en todas las herramientas

Construcción y pruebas

# Build the binary go build -o mcp-prometheus # Run tests go test ./..

Autenticación

Autenticación básica

export PROMETHEUS_USERNAME=miusuario export PROMETHEUS_PASSWORD=micontraseña

Autenticación por token portador

export PROMETHEUS_TOKEN=mi-token de portador

Soporte multi-tenant

Perfecto para Cortex, Mimir, Thanos y otras configuraciones multi-tenant:

export PROMETHEUS_ORGID=tenant-123

Gestión de errores

Completa gestión de errores con mensajes detallados:

• Falta de orientación en la configuración
• Detalles defallos de autenticación
• Solución de problemas deconectividad de red
• Asistencia para consultasPromQL no válidas
• Explicaciones deerrores de la API de Prometheus
• Gestión de errores decreación de clientes dinámicos

Contribución

1. Fork del repositorio
2. Cree una rama de características(git checkout -b feature/amazing-feature)
3. Confirme sus cambios(git commit -m 'Add some amazing feature')
4. Empuja a la rama(git push origin feature/amazing-feature)
5. Abrir una Pull Request

Licencia

Este proyecto está licenciado bajo los mismos términos que la implementación original en Python.