prometheus-mcp

Servidor MCP para métricas y observabilidad de Prometheus. Proporcione a Claude (o a cualquier agente compatible con MCP) acceso de lectura a su instancia de Prometheus: consulte métricas con PromQL, inspeccione alertas activas y explore objetivos de scraping, todo ello sin salir de la conversación.

¿Por qué otro MCP de Prometheus?

Las integraciones existentes de Prometheus requieren scripts personalizados o conocimiento directo de la API. Este servidor:

• Habla el Protocolo de Contexto de Modelo estándar a través de stdio: funciona con Claude Desktop, Claude Code, Cursor y cualquier cliente MCP.

• Es de solo lectura: las 5 herramientas incluyen readOnlyHint: true, por lo que no hay riesgo de modificar los datos de Prometheus.

• Devuelve salida de doble canal: JSON estructurado (structuredContent) para uso programático + Markdown (content) para visualización legible por humanos.

• Tiene mensajes de error procesables que indican la variable de entorno exacta a corregir y sugieren el siguiente paso.

• Admite token Bearer, autenticación básica HTTP o sin autenticación (común para implementaciones internas).

Herramientas

Instalación

pip install prometheus-mcp

O ejecútelo directamente sin instalar:

uvx prometheus-mcp

Configuración

Toda la configuración se realiza mediante variables de entorno:

Copie .env.example a .env y rellene sus valores.

Configuración de Claude Desktop / Claude Code

Añada a su configuración de MCP (claude_desktop_config.json o .claude/mcp.json):

{
  "mcpServers": {
    "prometheus": {
      "command": "prometheus-mcp",
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com",
        "PROMETHEUS_TOKEN": "your-token-here"
      }
    }
  }
}

O con uvx (no requiere instalación):

{
  "mcpServers": {
    "prometheus": {
      "command": "uvx",
      "args": ["prometheus-mcp"],
      "env": {
        "PROMETHEUS_URL": "https://prometheus.example.com"
      }
    }
  }
}

Docker

docker run --rm -e PROMETHEUS_URL=https://prometheus.example.com prometheus-mcp

Consultas de ejemplo

Una vez configurado, pregunte a Claude:

• "¿Qué métricas tiene Prometheus sobre las solicitudes HTTP?"

• "¿Cuál es la tasa de solicitudes actual para el servicio de pagos?"

• "Muéstrame el uso de CPU durante la última hora con una resolución de 5 minutos"

• "¿Hay alguna alerta activa? ¿Cuál es su gravedad?"

• "¿Qué objetivos de scraping están actualmente inactivos y por qué?"

• "¿Cuántas instancias de node-exporter están activas?"

Guía de uso de herramientas

prometheus_list_metrics

Devuelve todos los nombres de métricas que conoce Prometheus. Use pattern para filtrar por subcadena (sin distinguir entre mayúsculas y minúsculas). Empiece aquí cuando no sepa qué métricas están disponibles. La salida está limitada a 500 métricas con una indicación de truncamiento.

prometheus_query

Ejecute una expresión PromQL instantánea y obtenga los valores actuales. Devuelve el tipo de resultado (vector/escalar/matriz/cadena), el recuento de muestras y las etiquetas y valores por muestra.

Parámetros:

• query (requerido) — Expresión PromQL, p. ej. up, rate(http_requests_total[5m])

• time (opcional) — RFC3339 o marca de tiempo Unix; el valor predeterminado es ahora

prometheus_query_range

Ejecute una expresión PromQL durante una ventana de tiempo. Devuelve una serie por cada serie temporal coincidente con valores marcados con fecha y hora. El total de puntos de datos en todas las series está limitado a 5000.

Parámetros:

• query (requerido) — Expresión PromQL

• start / end (requerido) — RFC3339 o marcas de tiempo Unix

• step (requerido) — resolución como 15s, 1m, 5m

Prometheus rechaza los pasos que producirían > 11 000 puntos por serie (HTTP 422). Aumente el paso o reduzca el rango si esto sucede.

Nota: La API de rango de Prometheus no admite el filtrado por rama o confirmación: los filtros se expresan puramente en los comparadores de etiquetas de PromQL.

prometheus_list_alerts

Devuelve todas las alertas activas/pendientes con etiquetas (incluyendo alertname, severity), estado, tiempo de activación y valor actual. Incluye un resumen de estado (recuentos de disparo frente a pendientes).

prometheus_list_targets

Devuelve objetivos de scraping con nombre de trabajo, dirección de instancia, estado de salud (up/down/unknown), duración del último scraping en milisegundos y cualquier mensaje de error. Incluye un resumen por trabajo. Filtre por state: active (predeterminado), dropped o any.

Características de rendimiento

• Todas las herramientas utilizan una requests.Session persistente única con agrupación de conexiones.

• La sesión tiene trust_env = False para omitir los proxies de entorno (Prometheus suele ser un servicio interno).

• Las solicitudes agotan el tiempo de espera después de 30 segundos.

• prometheus_query_range limita la salida a 5000 puntos totales en todas las series: use un paso más grande para ventanas largas.

• prometheus_list_metrics devuelve hasta 500 métricas después del filtrado.

Desarrollo

git clone https://github.com/mshegolev/prometheus-mcp
cd prometheus-mcp
pip install -e '.[dev]'
pytest tests/ -v
ruff check src tests
ruff format src tests

Licencia

MIT — consulte LICENSE.