Prometheus MCP Server

Un servidor MCP para integrarse con Prometheus y consultar métricas.

Documentación

Servidor MCP de Prometheus

Dale a los asistentes de IA el poder de consultar tus métricas de Prometheus.

Un servidor de Model Context Protocol (MCP) que proporciona acceso a tus métricas y consultas de Prometheus a través de interfaces MCP estandarizadas, permitiendo a los asistentes de IA ejecutar consultas PromQL y analizar tus datos de métricas.

Comenzando

Requisitos previos

Servidor de Prometheus accesible desde tu entorno
Cliente compatible con MCP (Claude Desktop, VS Code, Cursor, Windsurf, etc.)

Métodos de instalación

Claude Desktop

Añade a tu configuración de Claude Desktop:

{
  "mcpServers": {
    "prometheus": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "PROMETHEUS_URL",
        "ghcr.io/pab1it0/prometheus-mcp-server:latest"
      ],
      "env": {
        "PROMETHEUS_URL": "<your-prometheus-url>"
      }
    }
  }
}

Claude Code

Instala a través de la CLI de Claude Code:

claude mcp add prometheus --env PROMETHEUS_URL=http://your-prometheus:9090 -- docker run -i --rm -e PROMETHEUS_URL ghcr.io/pab1it0/prometheus-mcp-server:latest

VS Code / Cursor / Windsurf

Añade a tu configuración de MCP en el IDE correspondiente:

{
  "prometheus": {
    "command": "docker",
    "args": [
      "run",
      "-i",
      "--rm",
      "-e",
      "PROMETHEUS_URL",
      "ghcr.io/pab1it0/prometheus-mcp-server:latest"
    ],
    "env": {
      "PROMETHEUS_URL": "<your-prometheus-url>"
    }
  }
}

Docker Desktop

La forma más sencilla de ejecutar el servidor MCP de Prometheus es a través de Docker Desktop:

Vía Catálogo MCP: Visita el Servidor MCP de Prometheus en Docker Hub y haz clic en el botón de arriba
Vía MCP Toolkit: Usa la extensión MCP Toolkit de Docker Desktop para descubrir e instalar el servidor
Configura tu conexión usando variables de entorno (consulta las Opciones de Configuración a continuación)

Configuración Manual con Docker

Ejecuta directamente con Docker:

# With environment variables
docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

# With authentication
docker run -i --rm \
  -e PROMETHEUS_URL="http://your-prometheus:9090" \
  -e PROMETHEUS_USERNAME="admin" \
  -e PROMETHEUS_PASSWORD="password" \
  ghcr.io/pab1it0/prometheus-mcp-server:latest

Helm Chart (Kubernetes)

Despliega en Kubernetes usando el Helm chart desde el registro OCI:

helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  --set prometheus.url="http://prometheus:9090"

Con autenticación:

helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  --set prometheus.url="http://prometheus:9090" \
  --set auth.username="admin" \
  --set auth.password="secret"

Con un archivo de valores personalizado:

helm install prometheus-mcp-server \
  oci://ghcr.io/pab1it0/charts/prometheus-mcp-server \
  --version 1.1.1 \
  -f values.yaml

Consulta los valores del chart para todas las opciones de configuración disponibles.

Opciones de Configuración

Variable	Descripción	Requerido
`PROMETHEUS_URL`	URL de tu servidor de Prometheus	Sí
`PROMETHEUS_URL_SSL_VERIFY`	Establecer en False para deshabilitar la verificación SSL	No
`PROMETHEUS_DISABLE_LINKS`	Establecer en True para deshabilitar los enlaces de la interfaz de Prometheus en los resultados de consultas (ahorra tokens de contexto)	No
`PROMETHEUS_REQUEST_TIMEOUT`	Tiempo de espera de solicitud en segundos para evitar solicitudes colgadas (protección DDoS)	No (predeterminado: 30)
`PROMETHEUS_USERNAME`	Nombre de usuario para autenticación básica	No
`PROMETHEUS_PASSWORD`	Contraseña para autenticación básica	No
`PROMETHEUS_TOKEN`	Token Bearer para autenticación	No
`PROMETHEUS_CLIENT_CERT`	Ruta al archivo de certificado de cliente para autenticación TLS mutua	No
`PROMETHEUS_CLIENT_KEY`	Ruta al archivo de clave privada del cliente para autenticación TLS mutua	No
`REQUESTS_CA_BUNDLE`	Ruta al archivo del paquete CA para verificar el certificado TLS del servidor (variable de entorno estándar de la biblioteca `requests`)	No
`ORG_ID`	ID de organización para configuraciones multiinquilino	No
`PROMETHEUS_MCP_SERVER_TRANSPORT`	Modo de transporte (stdio, http, sse)	No (predeterminado: stdio)
`PROMETHEUS_MCP_BIND_HOST`	Host para transporte HTTP	No (predeterminado: 127.0.0.1)
`PROMETHEUS_MCP_BIND_PORT`	Puerto para transporte HTTP	No (predeterminado: 8080)
`PROMETHEUS_MCP_STATELESS_HTTP`	Habilitar modo HTTP sin estado para soporte multi-réplica	No (predeterminado: False)
`PROMETHEUS_CUSTOM_HEADERS`	Encabezados personalizados como cadena JSON	No
`TOOL_PREFIX`	Prefijo para todos los nombres de herramientas (por ejemplo, `staging` resulta en `staging_execute_query`). Útil para ejecutar múltiples instancias dirigidas a diferentes entornos en Cursor	No

Herramientas Disponibles

Herramienta	Categoría	Descripción
`health_check`	Sistema	Punto final de verificación de salud para monitoreo de contenedores y verificación de estado
`execute_query`	Consulta	Ejecuta una consulta instantánea PromQL contra Prometheus
`execute_range_query`	Consulta	Ejecuta una consulta de rango PromQL con hora de inicio, hora de fin e intervalo de paso
`list_metrics`	Descubrimiento	Lista todas las métricas disponibles en Prometheus con soporte de paginación y filtrado
`get_metric_metadata`	Descubrimiento	Obtiene metadatos para una métrica o metadatos masivos con filtrado opcional
`get_targets`	Descubrimiento	Obtiene objetivos de scrape, con filtrado del lado del servidor `state`/`scrape_pool` y paginación opcional

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 de la ventana de contexto.

Características

Ejecuta consultas PromQL contra Prometheus
Descubre y explora métricas
- Lista métricas disponibles
- Obtén metadatos para métricas específicas
- Busca metadatos de métricas por nombre o descripción en una sola llamada
- Ve resultados de consultas instantáneas
- Ve resultados de consultas de rango con diferentes intervalos de paso
Soporte de autenticación
- Autenticación básica desde variables de entorno
- Autenticación con token Bearer desde variables de entorno
Soporte de contenedores Docker
Proporciona herramientas interactivas para asistentes de IA

Desarrollo

¡Las contribuciones son bienvenidas! Consulta nuestra Guía de Contribución para obtener información detallada sobre cómo comenzar, estándares de codificación y el proceso de solicitudes de extracción.

Este proyecto usa uv para gestionar dependencias. Instala uv siguiendo las instrucciones para tu plataforma:

curl -LsSf https://astral.sh/uv/install.sh | sh

Luego puedes crear un entorno virtual e instalar las dependencias con:

uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows
uv pip install -e .

Pruebas

El proyecto incluye un conjunto completo de pruebas que garantiza la funcionalidad y ayuda a prevenir regresiones.

Ejecuta las pruebas con pytest:

# Install development dependencies
uv pip install -e ".[dev]"

# Run the tests
pytest

# Run with coverage report
pytest --cov=src --cov-report=term-missing

Al agregar nuevas características, por favor también agrega las pruebas correspondientes.

Licencia

MIT