prometheus-mcp

prometheus-mcp

用于 Prometheus 指标和可观测性的 MCP 服务。 让 Claude（或任何兼容 MCP 的 Agent）以只读方式访问你的 Prometheus 实例——在对话中查询指标、检查活动告警并探索抓取目标。

为什么还需要另一个 Prometheus MCP？

现有的 Prometheus 集成需要自定义脚本或直接了解 API。这个服务：

• 通过 stdio 使用标准的 Model Context Protocol——可与 Claude Desktop、Claude Code、Cursor 及任何 MCP 客户端配合使用。
• 只读：全部 5 个工具都带有 readOnlyHint: true——完全不会修改 Prometheus 数据。
• 返回双通道输出：供程序使用的结构化 JSON（structuredContent）+ 便于人类阅读的 Markdown（content）。
• 提供可执行的错误消息，指出需要修正的确切环境变量，并建议下一步操作。
• 支持 Bearer token、HTTP Basic 认证或无认证（常见于内部部署）。

工具

工具	端点	描述
prometheus_list_metrics	GET /api/v1/label/__name__/values	列出所有指标名称，可选按子字符串筛选（上限 500）
prometheus_query	GET /api/v1/query	执行即时 PromQL 查询
prometheus_query_range	GET /api/v1/query_range	执行 PromQL 范围查询并返回时间序列
prometheus_list_alerts	GET /api/v1/alerts	列出活动和待处理的告警
prometheus_list_targets	GET /api/v1/targets	按健康状态和作业列出抓取目标

v4.0 高级告警关联功能

4.0 版新增强大功能，让 AI Agent 能够自主调查生产环境错误：

跨实例告警关联

• 自动识别多个 Prometheus 实例中的相关告警
• 按服务标识符对告警分组，了解事件影响范围
• 通过推断依赖方向，检测级联告警模式

根因分析

• 检测指标异常，并自动调整季节性因素
• 沿依赖链从症状追溯潜在根因
• 检测变更点，将告警与近期部署或配置变更关联起来
• 根据证据强度和影响分析，对根因候选项排序

依赖关系映射与健康状态

• 基于流量关联分析动态构建服务依赖关系图
• 跨集群依赖关系可视化，展示服务间的协作情况
• 通过合成健康探测评估依赖项的韧性
• 根据依赖项的脆弱性提供负载削减建议

趋势分析与基准比较

• 识别历史模式，发现重复出现的告警时间安排
• 预测容量，预判资源耗尽
• 通过与历史数据对比解决耗时，评估 MTTR
• 检测偏差，在模式被打破时触发更高优先级的通知

集成分析工具

• 新增 federation_analyze_alerts 工具，整合所有 v4.0 功能
• 统一输出格式，针对 AI Agent 使用进行了优化
• 通过一次工具调用提供全面的事件上下文

安装

pip install prometheus-mcp

或者无需安装，直接运行：

uvx prometheus-mcp

配置

所有配置均通过环境变量完成：

变量	必填	默认值	描述
PROMETHEUS_URL	是	—	Prometheus 服务 URL，例如 https://prometheus.example.com（末尾不要加斜杠）
PROMETHEUS_TOKEN	否	—	Bearer 令牌（优先于 Basic 身份验证）
PROMETHEUS_USERNAME	否	—	HTTP Basic 身份验证用户名
PROMETHEUS_PASSWORD	否	—	HTTP Basic 身份验证密码
PROMETHEUS_SSL_VERIFY	否	true	对自签名证书设置为 false

将 .env.example 复制为 .env，并填写相应值。

Claude Desktop / Claude Code 配置

将以下内容添加到 MCP 配置（claude_desktop_config.json 或 .claude/mcp.json）中：

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

也可使用 uvx（无需安装）：

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

示例查询

配置完成后，可以向 Claude 提问：

• “Prometheus 中有哪些关于 HTTP 请求的指标？”
• “支付服务当前的请求速率是多少？”
• “显示过去一小时的 CPU 使用情况，分辨率为 5 分钟”
• “目前有正在触发的告警吗？它们的严重性如何？”
• “哪些抓取目标目前处于关闭状态？原因是什么？”
• “有多少个 node-exporter 实例处于运行状态？”

工具使用指南

prometheus_list_metrics

返回 Prometheus 已知的所有指标名称。使用 pattern 按子字符串筛选（不区分大小写）。**不清楚有哪些可用指标时，请从这里开始。**输出最多包含 500 个指标，超出时会提示结果已截断。

prometheus_query

执行即时 PromQL 表达式并获取当前值。返回结果类型（vector/scalar/matrix/string）、样本数量，以及每个样本的标签和值。

参数：

• query（必填）— PromQL 表达式，例如 up、rate(http_requests_total[5m])
• time（可选）— RFC3339 或 Unix 时间戳；默认使用当前时间

prometheus_query_range

在指定时间范围内执行 PromQL 表达式。每个匹配的时间序列会返回一组带时间戳的值。所有序列的数据点总数上限为 5000。

参数：

• query（必填）— PromQL 表达式
• start / end（必填）— RFC3339 或 Unix 时间戳
• step（必填）— 分辨率，例如 15s、1m、5m

如果步长会导致每个序列产生超过 11,000 个数据点，Prometheus 会拒绝请求（HTTP 422）。出现这种情况时，请增大步长或缩小时间范围。

**注意：**Prometheus 范围 API 不支持按分支或提交筛选 — 筛选条件只能通过 PromQL 标签匹配器指定。

prometheus_list_alerts

返回所有活动或待处理的告警及其标签（包括 alertname、severity）、状态、激活时间和当前值。还会汇总状态（正在触发与待处理的数量）。

prometheus_list_targets

返回抓取目标及其作业名称、实例地址、健康状况（up/down/unknown）、上次抓取耗时（毫秒）和任何错误消息。还会按作业汇总。使用 state 筛选：active（默认值）、dropped 或 any。

性能特征

• 所有工具都使用一个持久化的 requests.Session，并启用连接池。
• 会话设置了 trust_env = False，以绕过环境代理（Prometheus 通常是内部服务）。
• 请求在 30 秒后超时。
• prometheus_query_range 的输出上限为所有序列合计 5000 个数据点 — 查询较长时间范围时，请使用更大的步长。
• prometheus_list_metrics 在筛选后最多返回 500 个指标。

开发

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

API 规范

本项目在 specs/ 目录中提供了 OpenAPI 3.0 规范，用于说明服务端公开的所有 MCP 工具。

验证该规范：

python3 specs/validate_spec.py

自动化

此仓库包含自动化脚本和 GitHub Actions 工作流，用于简化发布流程：

脚本

• scripts/auto-commit-push.sh - 自动提交并推送更改，可选择触发发布
• scripts/release.sh - 完整的发布自动化流程，包括流水线检查、版本更新和打标签

GitHub Actions 工作流

• post-push-check.yml - 监控每次推送后的测试流水线状态，并在提交上发表评论
• auto-release.yml - 用于创建发布版本的手动工作流，可递增版本号（补丁、次版本或主版本）

触发自动发布：

1. 前往 GitHub 中的 Actions 选项卡
2. 选择“Auto Release”工作流
3. 使用首选的版本递增类型运行该工作流

许可证

MIT — 请参阅 LICENSE。