prom-mcp

prom-mcp — 面向 AI Agent（Claude Code、Cursor）的 Prometheus MCP 服务

prom-mcp 是一个 Prometheus MCP 服务（Model Context Protocol），让 AI Agent 能够以生产级视角查看你的指标。 将 Claude Code、Cursor 或任何 MCP 客户端连接到 Prometheus，让 Agent 运行 PromQL 查询、结合规则定义解释触发中的告警，并在查询前发现实际存在的时间序列——让它进行调查，而不是猜测。

由一位负责生产环境值班的工程师打造，因此输出读起来像一份故障分诊记录，而不是原始 JSON 转储。

5 个工具 • 2 个资源 • 1 个分诊提示词 • 单个 Go 二进制文件 • 零依赖 • stdio

安装

Claude Desktop（MCPB，无需工具链）

下载适用于你平台的安装包，然后打开它或将其拖入 Claude Desktop（Settings → Extensions）。系统会提示你输入 Prometheus URL，默认值为 http://localhost:9090。

平台	MCPB 安装包
macOS（Apple silicon）	prom-mcp_v0.2.0_darwin_arm64.mcpb
macOS（Intel）	prom-mcp_v0.2.0_darwin_amd64.mcpb
Linux（x86_64）	prom-mcp_v0.2.0_linux_amd64.mcpb
Linux（arm64）	prom-mcp_v0.2.0_linux_arm64.mcpb

Claude Code

确保二进制文件位于 PATH 中（下载发布版本或使用 go install，见下文）：

claude mcp add prom -- prom-mcp

如果你的 Prometheus 不在 http://localhost:9090，请先在 shell 中设置 PROM_URL，或者为命令传入 --env PROM_URL=...。更多用法见 examples/claude-code.md。

Cursor

添加到 ~/.cursor/mcp.json（与 examples/cursor-mcp.json 相同）：

{
  "mcpServers": {
    "prom": {
      "command": "prom-mcp",
      "env": {
        "PROM_URL": "http://localhost:9090"
      }
    }
  }
}

VS Code

添加到 .vscode/mcp.json（与 examples/vscode-mcp.json 相同）：

{
  "servers": {
    "prom": {
      "command": "prom-mcp",
      "env": {
        "PROM_URL": "http://localhost:9090"
      }
    }
  }
}

Go install / 从源代码构建

go install github.com/aniketatgithub/prom-mcp@latest

git clone https://github.com/aniketatgithub/prom-mcp && cd prom-mcp
go build -o prom-mcp ./cmd/prom-mcp

四个平台的纯二进制文件也可在 v0.2.0 release 中获取，与上方的 MCPB 安装包一同提供。

可以询问什么

你的问题	prom-mcp 的操作
“为什么 NodeDown 正在触发？”	prom_alerts_explain 返回活动告警，并关联其规则表达式、组、for、标签和注释。
“实际有哪些 job 和实例？”	prom_series_discover 和 prom_label_values 会在编写查询前列出真实的时间序列和标签值。
“情况是否在恶化？”	prom_query_range 按时间序列汇总时间窗口：点数、首值、末值、最小值、最大值。

查看实际效果

告警分诊：节点为什么宕机？

查询前先发现实际存在的内容：

检查趋势：node1 的情况是否在恶化？

效果展示

向你的 Agent 提问 “节点为什么宕机了？”，告警工具会以分诊格式作答：

1 active alert(s)

[firing] NodeDown (since 2026-10-08T10:00:00Z, value 0)
  labels: {alertname="NodeDown", instance="node1:9100", job="node", severity="critical"}
  summary: Node node1:9100 is down
  description: Scrapes failing for 5m
  rule: up{job="node"} == 0
  group: node.rules
  for: 5m0s

此外还内置了 triage 提示词模板，按顺序引导 Agent 检查告警、发现指标和趋势。

工具

工具	功能
prom_query	即时执行 PromQL 查询，并以简洁的带标签序列和值呈现结果。
prom_query_range	查询过去 N 分钟内的数据；显示每个序列的数据点、首值、末值、最小值和最大值。
prom_alerts_explain	将活动告警与告警规则表达式、规则组、for 持续时间和注释关联起来。
prom_label_values	列出某个标签的实际值（可选指定范围），帮助 Agent 获取真实的 job/instance 名称。
prom_series_discover	检查是否存在符合标签匹配条件的序列，避免 Agent 臆造指标名称。

资源：prometheus://alerts（已说明的告警）、prometheus://config。提示词：triage。

无需服务即可试用

prom-mcp demo        # fixture-backed self-test: query, alert explanation, series discovery
prom-mcp query 'up'  # one-shot CLI query against $PROM_URL

配置

设置	环境变量	配置文件键
Prometheus 基础 URL	PROM_URL	base_url
Bearer 令牌（受身份验证保护的 Prometheus）	PROM_TOKEN	token
请求超时	PROM_TIMEOUT（例如 30s）	timeout_seconds
配置文件路径	PROM_CONFIG

配置文件为 JSON，按以下顺序查找：$PROM_CONFIG、./prom-mcp.json，然后是 ~/.prom-mcp.json：

{ "base_url": "https://prometheus.example.com", "token": "…", "timeout_seconds": 30 }

环境变量优先于文件。完全没有配置时，默认使用 http://localhost:9090。

为什么不直接向 Agent 提供原始 API 访问权限？

Agent 会被原始 Prometheus JSON 淹没，还会臆造并不存在的指标名称。prom-mcp 返回简洁、带标签且符合分诊场景的文本，并要求 Agent 先发现再查询。这就是只会猜测的 Agent 与会调查的 Agent 之间的区别。

单个 Go 二进制文件，无任何依赖，完全离线运行，可连接你自己的 Prometheus。

正在比较服务？请参阅 docs/comparison.md，了解与 pab1it0/prometheus-mcp-server 以及 Prometheus 组织的 prometheus/prometheus-mcp 的客观对比。

常见问题

哪些 AI 客户端可与 prom-mcp 配合使用？ 任何 MCP 客户端都可以：Claude Code、Cursor、Windsurf、Zed，以及自定义 Agent。它通过标准输入/输出使用以换行符分隔的 JSON-RPC 2.0 通信。

如何将 prom-mcp 连接到远程 Prometheus？ 添加服务时，将 PROM_URL 设为 Prometheus 基础 URL（例如 http://localhost:9090 或你的内部端点）。

AI Agent 能否说明 Prometheus 告警触发的原因？ 可以。prom_alerts_explain 会将活动告警与触发该告警的规则（表达式、摘要、描述）关联起来，让 Agent 能够推理原因，而不是只报告原始 JSON。

prom-mcp 需要 API 密钥或云服务吗？ 不需要。它是一个仅与 Prometheus 通信的本地单文件二进制程序。

prom-mcp 与其他 Prometheus MCP 服务相比如何？ 请参阅 docs/comparison.md。简而言之：prom-mcp 是专注于告警分诊的选项，提供 5 个工具；其他服务覆盖更多 Prometheus API，或包含更多部署组件。

这与向 Agent 暴露 Prometheus HTTP API 有何不同？ 原始 API 访问会返回嵌套 JSON，需要 Agent 自行解析，还容易导致其臆造指标名称。prom-mcp 会呈现简洁的带标签文本，将告警与触发它们的规则关联起来，限制过长的输出，并引导 Agent 先发现再查询。它还会针对瞬时故障重试，并支持 Bearer 令牌身份验证。

它能与远程或受身份验证保护的 Prometheus 配合使用吗？ 可以：设置 PROM_URL 和 PROM_TOKEN（或使用 JSON 配置文件）。请参阅“配置”。

支持哪些 Prometheus 版本？ 支持任何提供标准 HTTP API 的服务端（/api/v1/query、query_range、alerts、rules、series、label/<name>/values）。

许可证

MIT。请参阅 LICENSE。