prometheus-mcp

PyPI version Python versions License: MIT Tests

用于 Prometheus 指标和可观测性的 MCP 服务器。 让 Claude（或任何支持 MCP 的代理）能够读取您的 Prometheus 实例——无需离开对话即可使用 PromQL 查询指标、检查活动告警并探索抓取目标。

为什么选择另一个 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 auth 或 无认证（内部部署常见）。

工具

工具	端点	描述
`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`	按健康状况和作业列出抓取目标

安装

pip install prometheus-mcp

或者直接运行而不安装：

uvx prometheus-mcp

配置

所有配置均通过环境变量进行：

变量	必需	默认	描述
`PROMETHEUS_URL`	是	—	Prometheus 服务器 URL，例如 `https://prometheus.example.com`（末尾不要加斜杠）
`PROMETHEUS_TOKEN`	否	—	Bearer token（优先级高于 Basic auth）
`PROMETHEUS_USERNAME`	否	—	HTTP Basic auth 用户名
`PROMETHEUS_PASSWORD`	否	—	HTTP Basic auth 密码
`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 表达式并获取当前值。返回结果类型（向量/标量/矩阵/字符串）、样本计数以及每个样本的标签和值。

参数：

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

Prometheus 会拒绝导致每个序列产生 > 11,000 个点的步长（HTTP 422）。如果发生这种情况，请增加步长或缩小范围。

注意： Prometheus 范围 API 不支持按分支或提交进行过滤——过滤器纯粹以 PromQL 标签匹配器的形式表达。

`prometheus_list_alerts`

返回所有活动/待处理的告警，包含标签（包括 alertname, severity）、状态、激活时间和当前值。包含状态摘要（触发 vs 待处理计数）。

`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

许可证

MIT — 参见 LICENSE。

mshegolev/prometheus-mcp