Alertmanager

Um servidor Model Context Protocol (MCP) que permite que assistentes de IA se integrem ao Prometheus Alertmanager

GitHub
25
Experimente este MCPPatrocinado

Documentação

Prometheus Alertmanager MCP

GitHub license GitHub stars

Sumário

1. Introdução

Prometheus Alertmanager MCP é um servidor Model Context Protocol (MCP) para Prometheus Alertmanager. Ele permite que assistentes de IA e ferramentas consultem e gerenciem recursos do Alertmanager de forma programática e segura.

2. Recursos

  • Consultar status, alertas, silêncios, receptores e grupos de alertas do Alertmanager
  • Suporte a paginação inteligente para evitar estouro do contexto da LLM ao lidar com grandes quantidades de alertas
  • Criar, atualizar e excluir silêncios
  • Criar novos alertas
  • Suporte a autenticação (autenticação básica via variáveis de ambiente)
  • Suporte multi-tenant (via ALERTMANAGER_TENANT para Mimir/Cortex)
  • Suporte a conteinerização com Docker

3. Início Rápido

3.1. Pré-requisitos

  • Python 3.12+
  • uv (para gerenciamento rápido de dependências).
  • Docker (opcional, para implantação conteinerizada).
  • Garanta que seu servidor Prometheus Alertmanager esteja acessível a partir do ambiente onde você executará este servidor MCP.

3.2. Instalação via Smithery

Para instalar o Prometheus Alertmanager MCP Server para Claude Desktop automaticamente via Smithery:

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

3.3. Execução Local

  • Clone o repositório:
# Clone the repository
$ git clone https://github.com/ntk148v/alertmanager-mcp-server.git
  • Configure as variáveis de ambiente para seu servidor Prometheus, seja por meio de um arquivo .env ou variáveis de ambiente do 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

Suporte Multi-tenant

Para implantações Alertmanager multi-tenant (por exemplo, Grafana Mimir, Cortex), defina o ID do tenant por meio da variável de ambiente ALERTMANAGER_TENANT. O tenant é fixado na inicialização e nunca é obtido de um cabeçalho de requisição — valores X-Scope-OrgId fornecidos pelo chamador são ignorados para evitar que um cliente selecione um tenant arbitrário.

Configuração de transporte

Você pode controlar como o servidor MCP se comunica com os clientes usando as opções de transporte e as configurações de host/porta. Elas podem ser definidas por meio de flags de linha de comando (que têm precedência) ou variáveis de ambiente.

  • MCP_TRANSPORT: Modo de transporte. Um de stdio, http ou sse. Padrão: stdio.
  • MCP_HOST: Host/interface para vincular ao executar transportes http ou sse (usado pelo servidor uvicorn embutido). Padrão: 127.0.0.1.
  • MCP_PORT: Porta para escutar ao executar transportes http ou sse. Padrão: 8000.
  • MCP_API_KEY: Opcional chave de API/bearer. Quando definida, toda requisição http/sse deve enviar Authorization: Bearer <key> ou será rejeitada com 401. Quando não definida, o servidor registra um aviso de inicialização de que os transportes web não são autenticados. Fortemente recomendado para qualquer implantação acessível por rede.

Segurança: Para implantações acessíveis por rede, sempre defina MCP_API_KEY. Por padrão, o servidor vincula-se apenas ao loopback (127.0.0.1); exponha-o em 0.0.0.0 apenas atrás de um proxy confiável ou firewall quando precisar de acesso externo.

Exemplos:

Use variáveis de ambiente para definir padrões (flags de CLI ainda têm precedência):

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

Ou passe flags diretamente para substituir variáveis de ambiente:

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

Observações:

  • O transporte stdio comunica-se por entrada/saída padrão e ignora host/porta.

  • Os transportes http (HTTP streamable) e sse são servidos por meio de um aplicativo ASGI (uvicorn), portanto host/porta são respeitados ao usar esses transportes.

  • Adicione a configuração do servidor ao seu arquivo de configuração do cliente. Por exemplo, 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"
      }
    }
  }
}
  • Ou instale usando o comando make:
$ make install
  • Reinicie o Claude Desktop para carregar a nova configuração.
  • Agora você pode pedir ao Claude para interagir com o Alertmanager usando linguagem natural:
    • "Mostre-me os alertas atuais"
    • "Filtre alertas relacionados a problemas de CPU"
    • "Obtenha detalhes deste alerta"
    • "Crie um silêncio para este alerta pelas próximas 2 horas"

3.4. Execução com Docker

  • Execute com a imagem pré-construída (ou você pode construí-la você mesmo):
$ 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
  • Executando com Docker no 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 configuração passa as variáveis de ambiente do Claude Desktop para o contêiner Docker usando a flag -e com apenas o nome da variável e fornecendo os valores reais no objeto env.

4. Ferramentas

O servidor MCP expõe ferramentas para consultar e gerenciar o Alertmanager, seguindo sua API v2:

  • Obter status: get_status()
  • Listar alertas: get_alerts(filter, silenced, inhibited, active, count, offset)
    • Suporte a paginação: Retorna resultados paginados para evitar sobrecarregar o contexto da LLM
    • count: Número de alertas por página (padrão: 10, máximo: 25)
    • offset: Número de alertas a pular (padrão: 0)
    • Retorna: { "data": [...], "pagination": { "total": N, "offset": M, "count": K, "has_more": bool } }
  • Listar silêncios: get_silences(filter, count, offset)
    • Suporte a paginação: Retorna resultados paginados para evitar sobrecarregar o contexto da LLM
    • count: Número de silêncios por página (padrão: 10, máximo: 50)
    • offset: Número de silêncios a pular (padrão: 0)
    • Retorna: { "data": [...], "pagination": { "total": N, "offset": M, "count": K, "has_more": bool } }
  • Criar silêncio: post_silence(silence_dict)
  • Excluir silêncio: delete_silence(silence_id)
  • Listar receptores: get_receivers()
  • Listar grupos de alertas: get_alert_groups(silenced, inhibited, active, count, offset)
    • Suporte a paginação: Retorna resultados paginados para evitar sobrecarregar o contexto da LLM
    • count: Número de grupos de alertas por página (padrão: 3, máximo: 5)
    • offset: Número de grupos de alertas a pular (padrão: 0)
    • Retorna: { "data": [...], "pagination": { "total": N, "offset": M, "count": K, "has_more": bool } }
    • Observação: Grupos de alertas têm limites menores porque contêm todos os alertas dentro de cada grupo

Benefícios da Paginação

Ao trabalhar com ambientes que têm muitos alertas, silêncios ou grupos de alertas, o recurso de paginação ajuda:

  • Evitar estouro de contexto: Por padrão, apenas 10 itens são retornados por requisição
  • Navegação eficiente: LLMs podem iterar pelos resultados usando os parâmetros offset e count
  • Limites inteligentes: Máximo de 50 itens por página evita uso excessivo de contexto
  • Navegação clara: A flag has_more indica quando páginas adicionais estão disponíveis

Exemplo: Se você tem 100 alertas, a LLM pode buscá-los em blocos gerenciáveis (por exemplo, 10 por vez) e carregar apenas o que for necessário para análise.

Consulte src/alertmanager_mcp_server/server.py para detalhes completos da API.

5. Desenvolvimento

Contribuições são bem-vindas! Abra uma issue ou envie um pull request se tiver sugestões ou melhorias.

Este projeto usa uv para gerenciar dependências. Instale o uv seguindo as instruções para sua 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. Licença

Apache 2.0

Feito com ❤️ por @ntk148v