Alertmanager

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

GitHub
24
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 Model Context Protocol (MCP) para Prometheus Alertmanager. Permite a los asistentes y herramientas de IA consultar y gestionar los recursos de Alertmanager de forma programática y segura.

2. Características

  • Consultar el estado de Alertmanager, alertas, silencios, receptores y grupos de alertas
  • Soporte de paginación inteligente para evitar el desbordamiento de la ventana de contexto del 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 la cabecera X-Scope-OrgId para Mimir/Cortex)
  • Soporte de contenedores Docker

3. Inicio rápido

3.1. Requisitos previos

  • Python 3.12+
  • uv (para una gestión rápida de dependencias).
  • Docker (opcional, para despliegue en contenedores).
  • Asegúrate de que tu servidor 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 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 (p. ej., Grafana Mimir, Cortex), puedes especificar el ID de inquilino de dos formas:

  1. Configuración estática: Establece la variable de entorno ALERTMANAGER_TENANT
  2. Por solicitud: Incluye la cabecera X-Scope-OrgId en las solicitudes al servidor MCP

La cabecera X-Scope-OrgId tiene prioridad sobre la configuración estática, lo que permite cambiar de inquilino dinámicamente por solicitud.

Configuración del transporte

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

  • MCP_TRANSPORT: Modo de transporte. Uno de stdio, http o sse. Valor predeterminado: stdio.
  • MCP_HOST: Host/interfaz al que vincularse al ejecutar los transportes http o sse (utilizado por el servidor uvicorn integrado). Valor predeterminado: 0.0.0.0.
  • MCP_PORT: Puerto en el que escuchar al ejecutar los transportes http o sse. Valor predeterminado: 8000.

Ejemplos:

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

MCP_TRANSPORT=sse 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 la 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.

  • Añade la configuración del servidor a tu archivo de configuración del 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 las alertas relacionadas con problemas de CPU"
    • "Obtén los 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 precompilada (o puedes compilarla 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 solo con 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 del 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 del 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 del 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:

  • Evitar el desbordamiento del contexto: De forma predeterminada, solo se devuelven 10 elementos por solicitud
  • Navegación eficiente: Los LLM pueden recorrer 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 del 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 (p. ej., 10 a la vez) y cargar solo lo necesario para el análisis.

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

5. Desarrollo

¡Las contribuciones son bienvenidas! Abre un issue o envía un pull request si tienes sugerencias o mejoras.

Este proyecto usa uv para gestionar las 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