Prometheus Alertmanager MCP

目录

• 目录
• 1. 简介
• 2. 功能特性
• 3. 快速开始
  • 3.1. 前置条件
  • 3.2. 通过 Smithery 安装
  • 3.3. 本地运行
  • 3.4. Docker 运行
• 4. 工具
• 5. 开发
• 6. 许可证

1. 简介

Prometheus Alertmanager MCP 是一个面向 Prometheus Alertmanager 的 Model Context Protocol (MCP) 服务。它使 AI 助手和工具能够以编程方式安全地查询和管理 Alertmanager 资源。

2. 功能特性

• 查询 Alertmanager 状态、告警、静默、接收器和告警组
• 智能分页支持，防止在处理大量告警时出现大模型上下文窗口溢出
• 创建、更新和删除静默
• 创建新告警
• 认证支持（通过环境变量进行 Basic 认证）
• 多租户支持（通过 ALERTMANAGER_TENANT 支持 Mimir/Cortex）
• Docker 容器化支持

3. 快速开始

3.1. 前置条件

• Python 3.12+
• uv（用于快速依赖管理）。
• Docker（可选，用于容器化部署）。
• 确保你的 Prometheus Alertmanager 服务可以从运行此 MCP 服务的环境中访问。

3.2. 通过 Smithery 安装

通过 Smithery 为 Claude Desktop 自动安装 Prometheus Alertmanager MCP Server：

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

3.3. 本地运行

• 克隆仓库：

# Clone the repository
$ git clone https://github.com/ntk148v/alertmanager-mcp-server.git

• 通过 .env 文件或系统环境变量为你的 Prometheus 服务配置环境变量：

# 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

多租户支持

对于多租户 Alertmanager 部署（例如 Grafana Mimir、Cortex），通过 ALERTMANAGER_TENANT 环境变量设置租户 ID。租户在启动时固定，绝不从请求头中获取 —— 调用方提供的 X-Scope-OrgId 值会被忽略，以防止客户端选择任意租户。

传输配置

你可以使用传输选项以及 host/port 设置来控制 MCP 服务如何与客户端通信。这些设置既可以通过命令行标志（优先级更高）设置，也可以通过环境变量设置。

• MCP_TRANSPORT：传输模式。可选值为 stdio、http 或 sse。默认值：stdio。
• MCP_HOST：运行 http 或 sse 传输时绑定的主机/接口（由内嵌的 uvicorn 服务使用）。默认值：127.0.0.1。
• MCP_PORT：运行 http 或 sse 传输时监听的端口。默认值：8000。
• MCP_API_KEY：可选 bearer/API 密钥。设置后，每个 http/sse 请求都必须发送 Authorization: Bearer <key>，否则会以 401 拒绝。未设置时，服务会在启动时记录警告，提示 Web 传输未经过身份验证。对于任何可通过网络访问的部署，强烈建议设置此项。

安全性：对于可网络访问的部署，务必设置 MCP_API_KEY。默认情况下，服务仅绑定到回环地址（127.0.0.1）；只有在需要外部访问时，才应将其暴露在 0.0.0.0 上，并且要置于可信代理或防火墙之后。

示例：

使用环境变量设置默认值（命令行标志仍会覆盖）：

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

或者直接传入标志以覆盖环境变量：

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

说明：

• stdio 传输通过标准输入/输出通信，并忽略 host/port。

• http（可流式 HTTP）和 sse 传输通过 ASGI 应用（uvicorn）提供服务，因此使用这些传输时会遵循 host/port。

• 将服务配置添加到你的客户端配置文件中。例如，对于 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"
      }
    }
  }
}

• 或者使用 make 命令安装：

$ make install

• 重启 Claude Desktop 以加载新配置。
• 现在你可以让 Claude 使用自然语言与 Alertmanager 交互：
  • "Show me current alerts"
  • "Filter alerts related to CPU issues"
  • "Get details for this alert"
  • "Create a silence for this alert for the next 2 hours"

3.4. Docker Run

• 使用预构建镜像运行它（或者你也可以自行构建）：

$ 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

• 在 Claude Desktop 中使用 Docker 运行：

{
  "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"
      }
    }
  }
}

此配置通过使用 -e 标志并仅提供变量名，将环境变量从 Claude Desktop 传递到 Docker 容器，并在 env 对象中提供实际值。

4. 工具

MCP 服务暴露了用于查询和管理 Alertmanager 的工具，遵循其 API v2：

• 获取状态：get_status()
• 列出告警：get_alerts(filter, silenced, inhibited, active, count, offset)
  • 分页支持：返回分页结果，以避免使大模型上下文过载
  • count：每页告警数量（默认值：10，最大值：25）
  • offset：跳过的告警数量（默认值：0）
  • 返回：{ "data": [...], "pagination": { "total": N, "offset": M, "count": K, "has_more": bool } }
• 列出静默：get_silences(filter, count, offset)
  • 分页支持：返回分页结果，以避免使大模型上下文过载
  • count：每页静默数量（默认值：10，最大值：50）
  • offset：跳过的静默数量（默认值：0）
  • 返回：{ "data": [...], "pagination": { "total": N, "offset": M, "count": K, "has_more": bool } }
• 创建静默：post_silence(silence_dict)
• 删除静默：delete_silence(silence_id)
• 列出接收器：get_receivers()
• 列出告警组：get_alert_groups(silenced, inhibited, active, count, offset)
  • 分页支持：返回分页结果，以避免使大模型上下文过载
  • count：每页告警组数量（默认值：3，最大值：5）
  • offset：跳过的告警组数量（默认值：0）
  • 返回：{ "data": [...], "pagination": { "total": N, "offset": M, "count": K, "has_more": bool } }
  • 注意：告警组的限制更低，因为每个组中都包含其所有告警

分页优势

在处理包含大量告警、静默或告警组的环境时，分页功能有所帮助：

• 防止上下文溢出：默认每次请求仅返回 10 条记录
• 高效浏览：LLM 可以使用 offset 和 count 参数遍历结果
• 智能限制：每页最多 50 条记录，防止过度使用上下文
• 清晰的导航：has_more 标志指示何时有更多页面可用

示例：如果你有 100 条告警，LLM 可以分块获取它们（例如每次 10 条），并且只加载分析所需的内容。

查看 src/alertmanager_mcp_server/server.py 了解完整的 API 详情。

5. 开发

欢迎贡献！如果你有任何建议或改进，请提交 issue 或 pull request。

本项目使用 uv 来管理依赖。请根据你的平台说明安装 uv。

# 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. 许可证

Apache 2.0

---