prometheus-mcp

用于 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 或 无认证（内部部署常见）。

Related MCP server: Prometheus MCP Server

工具

安装

pip install prometheus-mcp

或者直接运行而不安装：

uvx prometheus-mcp

配置

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

将 .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。