Alertmanager

Un servidor del Protocolo de Contexto del Modelo (MCP) que permite a los asistentes de IA integrarse con Prometheus Alertmanager

GitHub
25
Prueba este MCPPatrocinado

Documentación

Prometheus Alertmanager MCP

GitHub license GitHub stars

Tabla de Contenidos

1. Introducción

Prometheus Alertmanager MCP es un servidor de Protocolo de Contexto de Modelo (MCP) para Prometheus Alertmanager. Permite a los asistentes de IA y herramientas consultar y gestionar recursos de Alertmanager de forma programática y segura.

2. Características

  • Consultar estado de Alertmanager, alertas, silencios, receptores y grupos de alertas
  • Soporte de paginación inteligente para evitar el desbordamiento del contexto de LLM al manejar grandes cantidades de alertas
  • Crear, actualizar y eliminar silencios
  • Crear nuevas alertas
  • Soporte de autenticación (autenticación básica mediante variables de entorno)
  • Soporte multiinquilino (mediante ALERTMANAGER_TENANT para Mimir/Cortex)
  • Soporte de contenedorización con Docker

3. Inicio Rápido

3.1. Requisitos Previos

  • Python 3.12+
  • uv (para gestión rápida de dependencias).
  • Docker (opcional, para despliegue contenerizado).
  • Asegúrate de que tu servidor de Prometheus Alertmanager sea accesible desde el entorno donde ejecutarás este servidor MCP.

3.2. Instalación mediante Smithery

Para instalar Prometheus Alertmanager MCP Server para Claude Desktop automáticamente mediante Smithery:

npx -y @smithery/cli install @ntk148v/alertmanager-mcp-server --client claude

3.3. Ejecución Local

  • Clona el repositorio:
# Clone the repository
$ git clone https://github.com/ntk148v/alertmanager-mcp-server.git
  • Configura las variables de entorno para tu servidor de Prometheus, ya sea mediante un archivo .env o variables de entorno del sistema:
# Set environment variables (see .env.sample)
ALERTMANAGER_URL=http://your-alertmanager:9093
ALERTMANAGER_USERNAME=your_username  # optional
ALERTMANAGER_PASSWORD=your_password  # optional
ALERTMANAGER_TENANT=your_tenant_id   # optional, for multi-tenant setups

Soporte Multiinquilino

Para despliegues de Alertmanager multiinquilino (por ejemplo, Grafana Mimir, Cortex), establece el ID de inquilino mediante la variable de entorno ALERTMANAGER_TENANT. El inquilino se fija al inicio y nunca se toma de un encabezado de solicitud — los valores de X-Scope-OrgId proporcionados por el llamador se ignoran para evitar que un cliente seleccione un inquilino arbitrario.

Configuración de transporte

Puedes controlar cómo el servidor MCP se comunica con los clientes usando las opciones de transporte y la configuración de host/puerto. Estas se pueden establecer mediante banderas de línea de comandos (que tienen prioridad) o mediante variables de entorno.

  • MCP_TRANSPORT: Modo de transporte. Uno de stdio, http o sse. Predeterminado: stdio.
  • MCP_HOST: Host/interfaz a la que vincularse al ejecutar transportes http o sse (usado por el servidor uvicorn integrado). Predeterminado: 127.0.0.1.
  • MCP_PORT: Puerto en el que escuchar al ejecutar transportes http o sse. Predeterminado: 8000.
  • MCP_API_KEY: Opcional clave de portador/API. Cuando se establece, cada solicitud http/sse debe enviar Authorization: Bearer <key> o se rechaza con 401. Cuando no se establece, el servidor registra una advertencia de inicio de que los transportes web no están autenticados. Muy recomendado para cualquier despliegue accesible a través de una red.

Seguridad: Para despliegues accesibles por red, establece siempre MCP_API_KEY. Por defecto, el servidor se vincula solo a loopback (127.0.0.1); expónlo en 0.0.0.0 solo detrás de un proxy de confianza o firewall cuando requieras acceso externo.

Ejemplos:

Usa variables de entorno para establecer valores predeterminados (las banderas CLI aún tienen prioridad):

MCP_TRANSPORT=sse MCP_API_KEY=change-me MCP_HOST=0.0.0.0 MCP_PORT=8080 python3 -m src.alertmanager_mcp_server.server

O pasa banderas directamente para anular las variables de entorno:

python3 -m src.alertmanager_mcp_server.server --transport http --host 127.0.0.1 --port 9000

Notas:

  • El transporte stdio se comunica a través de entrada/salida estándar e ignora host/puerto.

  • Los transportes http (HTTP transmisible) y sse se sirven mediante una aplicación ASGI (uvicorn), por lo que se respetan host/puerto al usar esos transportes.

  • Agrega la configuración del servidor a tu archivo de configuración de cliente. Por ejemplo, para Claude Desktop:

{
  "mcpServers": {
    "alertmanager": {
      "command": "uv",
      "args": [
        "--directory",
        "<full path to alertmanager-mcp-server directory>",
        "run",
        "src/alertmanager_mcp_server/server.py"
      ],
      "env": {
        "ALERTMANAGER_URL": "http://your-alertmanager:9093s",
        "ALERTMANAGER_USERNAME": "your_username",
        "ALERTMANAGER_PASSWORD": "your_password"
      }
    }
  }
}
  • O instálalo usando el comando make:
$ make install
  • Reinicia Claude Desktop para cargar la nueva configuración.
  • Ahora puedes pedirle a Claude que interactúe con Alertmanager usando lenguaje natural:
    • "Muéstrame las alertas actuales"
    • "Filtra alertas relacionadas con problemas de CPU"
    • "Obtén detalles de esta alerta"
    • "Crea un silencio para esta alerta durante las próximas 2 horas"

3.4. Ejecución con Docker

  • Ejecútalo con la imagen preconstruida (o puedes construirla tú mismo):
$ docker run -e ALERTMANAGER_URL=http://your-alertmanager:9093 \
    -e ALERTMANAGER_USERNAME=your_username \
    -e ALERTMANAGER_PASSWORD=your_password \
    -e ALERTMANAGER_TENANT=your_tenant_id \
    -p 8000:8000 ghcr.io/ntk148v/alertmanager-mcp-server
  • Ejecución con Docker en Claude Desktop:
{
  "mcpServers": {
    "alertmanager": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "ALERTMANAGER_URL",
        "-e",
        "ALERTMANAGER_USERNAME",
        "-e",
        "ALERTMANAGER_PASSWORD",
        "ghcr.io/ntk148v/alertmanager-mcp-server:latest"
      ],
      "env": {
        "ALERTMANAGER_URL": "http://your-alertmanager:9093s",
        "ALERTMANAGER_USERNAME": "your_username",
        "ALERTMANAGER_PASSWORD": "your_password"
      }
    }
  }
}

Esta configuración pasa las variables de entorno de Claude Desktop al contenedor Docker usando la bandera -e con solo el nombre de la variable, y proporcionando los valores reales en el objeto env.

4. Herramientas

El servidor MCP expone herramientas para consultar y gestionar Alertmanager, siguiendo su API v2:

  • Obtener estado: get_status()
  • Listar alertas: get_alerts(filter, silenced, inhibited, active, count, offset)
    • Soporte de paginación: Devuelve resultados paginados para evitar abrumar el contexto de LLM
    • count: Número de alertas por página (predeterminado: 10, máximo: 25)
    • offset: Número de alertas a omitir (predeterminado: 0)
    • Devuelve: { "data": [...], "pagination": { "total": N, "offset": M, "count": K, "has_more": bool } }
  • Listar silencios: get_silences(filter, count, offset)
    • Soporte de paginación: Devuelve resultados paginados para evitar abrumar el contexto de LLM
    • count: Número de silencios por página (predeterminado: 10, máximo: 50)
    • offset: Número de silencios a omitir (predeterminado: 0)
    • Devuelve: { "data": [...], "pagination": { "total": N, "offset": M, "count": K, "has_more": bool } }
  • Crear silencio: post_silence(silence_dict)
  • Eliminar silencio: delete_silence(silence_id)
  • Listar receptores: get_receivers()
  • Listar grupos de alertas: get_alert_groups(silenced, inhibited, active, count, offset)
    • Soporte de paginación: Devuelve resultados paginados para evitar abrumar el contexto de LLM
    • count: Número de grupos de alertas por página (predeterminado: 3, máximo: 5)
    • offset: Número de grupos de alertas a omitir (predeterminado: 0)
    • Devuelve: { "data": [...], "pagination": { "total": N, "offset": M, "count": K, "has_more": bool } }
    • Nota: Los grupos de alertas tienen límites más bajos porque contienen todas las alertas dentro de cada grupo

Beneficios de la Paginación

Al trabajar con entornos que tienen muchas alertas, silencios o grupos de alertas, la función de paginación ayuda:

  • Prevenir el desbordamiento de contexto: Por defecto, solo se devuelven 10 elementos por solicitud
  • Navegación eficiente: Los LLM pueden iterar a través de los resultados usando los parámetros offset y count
  • Límites inteligentes: Un máximo de 50 elementos por página evita el uso excesivo de contexto
  • Navegación clara: La bandera has_more indica cuándo hay páginas adicionales disponibles

Ejemplo: Si tienes 100 alertas, el LLM puede obtenerlas en fragmentos manejables (por ejemplo, 10 a la vez) y cargar solo lo necesario para el análisis.

Consulta src/alertmanager_mcp_server/server.py para obtener detalles completos de la API.

5. Desarrollo

¡Las contribuciones son bienvenidas! Abre un problema o envía una solicitud de extracción si tienes sugerencias o mejoras.

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

# Clone the repository
$ git clone https://github.com/ntk148v/alertmanager-mcp-server.git
$ cd alertmanager-mcp-server
$ make setup
# Run test
$ make test
# Run in development mode
$ mcp dev src/alertmanager_mcp_server/server.py

# Install in Claude Desktop
$ make install

6. Licencia

Apache 2.0

Hecho con ❤️ por @ntk148v