AI导哈

Prometheus MCP服务器

prom-mcp是一个流式HTTP MCP服务器，用于查询Prometheus兼容的API，专为AI代理设计，提供指标发现、PromQL执行、查询分析、警报上下文和运行时诊断等功能。

  • by jpetrucciani
  • Rust
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 jpetrucciani/prom-mcp

使用说明

舞会mcp

prom-mcp 是一个可流式传输的HTTP MCP服务器，用于查询与Prometheus兼容的API，专为AI代理构建。

它公开了一个MCP端点和一组高信号工具，用于度量发现、PromQL执行、查询分析、警报上下文和运行时诊断。

为什么舞会mcp

  • 专为Prometheus、Mimir、Thanos和VictoriaMetrics API表面设计。
  • 默认情况下，范围宽度、估计系列计数和估计样本的查询控件是安全的。
  • 响应整形模式(raw, summary, smart, table)针对代理工作流进行了调优。
  • 每会话MCP速率限制，以保护上游普罗米修斯。
  • 可选的内存操作历史记录，带有用于调试的查询哈希。
  • MCP和调试端点的可选静态标头身份验证。
  • 基于浏览器的MCP客户端的可选CORS分配列表。
  • 标准操作端点： /healthz, /readyz, /metrics.

安装

选项1，GitHub发布二进制文件

从下载最新存档 发布 对于您的平台：

  • linux-amd64
  • linux-aarch64
  • macos-aarch64
  • windows-amd64

选项2，容器图像

已发布的图片可在 ghcr.io/jpetrucciani/prom-mcp:<version>.

docker run --rm -p 8081:8081 \
  -v "$(pwd)/config.toml:/config.toml:ro" \
  ghcr.io/jpetrucciani/prom-mcp:<version> \
  --config /config.toml

选项3，从源代码构建

cargo install --path .
prom-mcp --help

快速开始

  1. 从示例配置开始：
cp config.example.toml config.toml
  1. 运行服务器：
prom-mcp --config ./config.toml
  1. 验证基本健康状况：
curl -sS http://127.0.0.1:8081/healthz
curl -sS http://127.0.0.1:8081/readyz
curl -sS http://127.0.0.1:8081/metrics | head

您还可以使用环境变量启动：

PROM_MCP_PROMETHEUS_URL=http://127.0.0.1:9090 \
PROM_MCP_LISTEN=0.0.0.0:8081 \
prom-mcp

对于从浏览器进行本地MCP检查器调试：

PROM_MCP_CORS_ALLOWED_ORIGINS='*' prom-mcp --config ./config.toml

MCP端点

  • POST /mcp，可流式传输HTTP MCP传输端点。

MCP握手顺序：

  1. 呼叫 initialize.
  2. 发送 notifications/initialized.
  3. 呼叫 tools/list，然后调用工具。

客户端端点配置示例：

{
  "mcpServers": {
    "prometheus": {
      "transport": "streamable-http",
      "url": "http://127.0.0.1:8081/mcp"
    }
  }
}

工具目录

发现和模式

  • prom_describe_schema
  • prom_list_metrics
  • prom_describe_metric
  • prom_list_labels
  • prom_label_values
  • prom_search_label_values
  • prom_series

查询与分析

  • prom_query_instant
  • prom_query_range
  • prom_build_query
  • prom_run_saved_query
  • prom_query_stats
  • prom_compare_ranges
  • prom_top_series
  • prom_detect_anomalies
  • prom_explain_query

警报和规则

  • prom_list_alerts
  • prom_list_rules
  • prom_alert_history
  • prom_suggest_alert

运行时诊断

  • prom_check_health
  • prom_tsdb_stats

接受的时间输入 start, end，或 time 接受ISO-8601/RFC3339字符串、Unix纪元秒等 1435781451，分数Unix秒，例如 1435781451.781相对持续时间，例如 10m，以及配置的时区支持的自然语言值。面向范围的工具也可以接受 range例如 range: "10m"，作为以结尾的窗口的快捷方式 end 或 now；使用其中之一 range 或 start不是两者都有。

prom_label_values 支持可选 pattern, prefix，以及 limit 字段以减少噪声标签值有效载荷。 prom_search_label_values 在选定标签或发现的标签之间搜索值 labels 省略。

配置

配置优先级：

  1. 配置文件， --config <path> 或本地 config.toml 如果存在。
  2. 环境变量， PROM_MCP_*.
  3. CLI标志，最高优先级。

参考配置： config.example.toml.

常见环境变量：

  • PROM_MCP_LISTEN
  • PROM_MCP_TIMEZONE
  • PROM_MCP_LOG_LEVEL
  • PROM_MCP_LOG_FORMAT (json 启用结构化日志记录）
  • PROM_MCP_AUTH_HEADER
  • PROM_MCP_AUTH_TOKEN
  • PROM_MCP_CORS_ALLOWED_ORIGINS
  • PROM_MCP_PROMETHEUS_URL
  • PROM_MCP_PROMETHEUS_TENANT_ID
  • PROM_MCP_PROMETHEUS_AUTH_TYPE (none, basic, bearer)
  • PROM_MCP_PROMETHEUS_USERNAME
  • PROM_MCP_PROMETHEUS_PASSWORD
  • PROM_MCP_PROMETHEUS_TOKEN
  • PROM_MCP_PROMETHEUS_CA_CERT
  • PROM_MCP_PROMETHEUS_BACKEND_TYPE (prometheus, mimir, thanos, victoriametrics)
  • PROM_MCP_GUARDRAILS_MAX_RANGE
  • PROM_MCP_GUARDRAILS_MAX_SERIES
  • PROM_MCP_GUARDRAILS_MAX_SAMPLES
  • PROM_MCP_RATE_LIMIT_ENABLED
  • PROM_MCP_RATE_LIMIT_RPS
  • PROM_MCP_RATE_LIMIT_BURST
  • PROM_MCP_ACTION_HISTORY_ENABLED
  • PROM_MCP_ACTION_HISTORY_MAX_ENTRIES
  • PROM_MCP_ACTION_HISTORY_ENDPOINT_ENABLED

Prometheus身份验证规则：

  • auth_type = "basic" 需要用户名和密码。
  • auth_type = "bearer" 需要令牌。

后端兼容性说明：

  • 当 prometheus.backend_type 是 mimir 或 thanos, prom-mcp 可以重试请求 /prometheus/api/v1/... 当平原 /api/v1/... 返回404。

MCP访问控制

除非满足以下条件，否则禁用静态标头身份验证 server.auth_token 设置为非空值。当启用时， /mcp, /mcp/*, /debug，以及 /debug/* 请求必须包含具有确切令牌值的配置标头。

默认标题为 x-prom-mcp-token；用以下命令覆盖它 server.auth_header, --auth-header，或 PROM_MCP_AUTH_HEADER. /healthz, /readyz，以及 /metrics 保持打开状态，以便进行探头和刮擦。

PROM_MCP_AUTH_TOKEN="$PROM_MCP_TOKEN" prom-mcp
curl -H "x-prom-mcp-token: $PROM_MCP_TOKEN" http://127.0.0.1:8081/mcp

CORS被禁用，除非 server.cors_allowed_origins 不是空的。例如，允许的来源必须是唯一的来源 http://localhost:6274，而不是像这样的路径 http://localhost:6274/mcp.使用 server.cors_allowed_origins = ["*"], --cors-allowed-origin '*'，或 PROM_MCP_CORS_ALLOWED_ORIGINS='*' 允许任何浏览器来源。

MCP Inspector从其自己的localhost源运行浏览器UI，因此浏览器在调用之前会强制执行CORS prom-mcp.CLI工具，如 curl 不受浏览器CORS检查。CORS预检在静态头认证之前处理，因为浏览器不会在预检时发送自定义认证头。

CLI测试

检查CORS飞行前行为：

curl -i -X OPTIONS http://127.0.0.1:8081/mcp \
  -H 'Origin: http://localhost:6274' \
  -H 'Access-Control-Request-Method: POST' \
  -H 'Access-Control-Request-Headers: content-type,x-prom-mcp-token,mcp-session-id'

预期有匹配的CORS分配列表： 204 No Content 和一个 access-control-allow-origin 头球

发送MCP初始化请求：

curl -i http://127.0.0.1:8081/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "x-prom-mcp-token: $PROM_MCP_TOKEN" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "curl", "version": "0.0.0"}
    }
  }'

HTTP端点

  • POST /mcp，MCP传输，静态标头在以下情况下受到保护 server.auth_token 已设置。
  • GET /healthz，活性终点。
  • GET /readyz，就绪端点，返回 503 当上游不可用时。
  • GET /metrics普罗米修斯自我度量。
  • GET /debug/recent-actions，可选操作历史终结点，仅在启用时，静态标头受保护 server.auth_token 已设置。

故障排除

  • /mcp 或 /debug/* 返回401，发送配置的auth头或取消设置 server.auth_token.
  • MCP检查器报告CORS错误，将其浏览器源添加到 server.cors_allowed_origins 或使用 ["*"] 用于本地调试。

码头工人

发布自动化发布多拱形图像，并在标签匹配时发布存档 v*.

本地映像构建：

mkdir -p target/container/release
cp target/release/prom-mcp target/container/release/prom-mcp
docker build -t prom-mcp:local .
docker run --rm -p 8081:8081 prom-mcp:local --help

发展

cargo fmt
cargo clippy --all --benches --tests --examples --all-features -- -D warnings -W clippy::collapsible_else_if
cargo test --verbose

如果您使用Nix：

nix develop

相关 MCP