普罗米修斯-MCP
项目介绍
Prometheus MCP
一个生产就绪的 MCP（模型上下文协议）服务器，集成了 Prometheus 客户端，使通过 MCP 协议无缝执行 PromQL 查询成为可能。从 Claude、OpenAI 等 AI 助手中直接执行 Prometheus 查询、分析指标并监控基础设施。
基于 mcp-forge 🔧
该项目基于 @achetronic 提供的出色 MCP 服务器模板，该模板自带生产就绪的 OAuth 认证、JWT 验证以及企业级特性。
动机
监控和可观测性对于现代应用程序至关重要，但要从 AI 助手中访问 Prometheus 指标，需要一个无缝集成层。此 MCP 服务器填补了这一空白，允许您通过与 AI 工具的自然语言交互直接查询 Prometheus，使得监控更加便捷和直观。
特性
-
🔍 完整的 Prometheus 集成
- 使用
prometheus_query执行即时 PromQL 查询 - 使用
prometheus_range_query执行范围查询 - 使用
prometheus_list_metrics列出所有可用的指标
- 使用
-
🔐 企业认证支持
- HTTP 基本认证
- Bearer Token 认证（JWT/API 令牌）
- 多租户支持，使用
X-Scope-OrgId头
-
🏢 多平台兼容性
- 纯 Prometheus 实例
- Cortex 多租户设置
- Thanos Query 部署
- Grafana Cloud 集成
- 具有自定义头的企业代理
-
🛡️ 生产就绪的安全性
- 符合 OAuth RFC 8414 和 RFC 9728 标准
- JWT 验证（委托或本地 JWKS）
- 可配置的访问日志，包括字段排除/红字处理
-
🚀 基础设施特性
- 支持 Docker 容器化
- 用于 Kubernetes 部署的 Helm Chart
- 结构化的 JSON 日志记录
- 全面的错误处理和故障排除
Prometheus 配置
基础设置
在您的 config.yaml 中添加 Prometheus 配置：
prometheus:
url: "http://localhost:9090" # Prometheus 服务器 URL
timeout: "30s" # 可选请求超时时间
高级配置带认证
prometheus:
url: "https://prometheus.company.com"
timeout: "30s"
org_id: "tenant-1" # 多租户系统中的 X-Scope-OrgId 头
auth:
type: "basic" # 类型： "basic", "token" 或空表示无认证
username: "prometheus-user" # 基本认证用户名
password: "secret-password" # 基本认证密码
Bearer Token 配置
prometheus:
url: "https://prometheus.company.com"
timeout: "30s"
org_id: "my-org-123"
auth:
type: "token"
token: "eyJhbGciOiJIUzI1NiIs..." # JWT 或 API 令牌
配置选项
url（必需）：Prometheus 服务器 URLtimeout（可选）：请求超时时间（例如："30s", "1m"）org_id（可选）：X-Scope-OrgId头的值，适用于：- Cortex 多租户部署
- Thanos 的租户隔离
- 多租户代理后面的 Prometheus
auth.type（可选）：认证类型"basic"：HTTP 基本认证"token"：Bearer Token 认证- 空或未指定：无认证
auth.username和auth.password：基本认证凭据auth.token：Bearer 认证令牌
常见用例
纯 Prometheus（无认证）
prometheus:
url: "http://localhost:9090"
Cortex 多租户
prometheus:
url: "http://cortex-gateway:8080/prometheus"
org_id: "tenant-acme"
auth:
type: "basic"
username: "cortex-user"
password: "cortex-pass"
Thanos Query 带租户头
prometheus:
url: "http://thanos-query:9090"
org_id: "team-backend"
Grafana Cloud 带 API Token
prometheus:
url: "https://prometheus.grafana.net/api/prom"
auth:
type: "token"
token: "glc_eyJrIjoiN3..." # Grafana Cloud API 密钥
可用的 MCP 工具
1. prometheus_query
对 Prometheus 执行即时 PromQL 查询。
参数：
query（必需）：要执行的 PromQL 查询time（可选）：RFC3339 格式的时间戳。如果没有提供，则使用当前时间
示例：
{
"query": "up",
"time": "2024-01-15T10:30:00Z"
}
2. prometheus_range_query
对 Prometheus 执行 PromQL 范围查询。
参数：
query（必需）：要执行的 PromQL 查询start（必需）：RFC3339 格式的开始时间end（必需）：RFC3339 格式的结束时间step（可选）：步长持续时间（例如："30s", "1m", "5m"）。默认为 "1m"
示例：
{
"query": "rate(http_requests_total[5m])",
"start": "2024-01-15T10:00:00Z",
"end": "2024-01-15T11:00:00Z",
"step": "1m"
}
3. prometheus_list_metrics
列出 Prometheus 中所有可用的指标。
参数： 无。
示例响应：
{
"total_metrics": 245,
"metrics": [
"up",
"prometheus_build_info",
"http_requests_total"
]
}
部署
生产环境 🚀
使用位于 chart/ 目录中的 Helm Chart 部署到 Kubernetes。
我们对生产环境中远程服务器的建议：
- 当使用 MCP 会话时，在 MCP 服务器前面使用一致的哈希环 HTTP 代理
- 在 MCP 前面使用执行 JWT 验证的 HTTP 代理，而不是使用内置中间件：
- 以与我们的中间件相同的方式保护您的 MCP，但使用经过充分测试且可扩展的代理
- 改善您的开发体验，因为您无需做任何事情，只需开发您的 MCP 工具
- 使用 OIDP：
- 覆盖 OAuth 动态客户端注册
- 能够定制您的 JWT 声明。
👉 Keycloak 覆盖了您在 OAuth2 方面所需的一切
👉 Istio 覆盖了在 MCP 前面验证 JWT 所需的一切
👉 Hashrouter 使用可配置且真正一致的哈希环来路由流量，因此您的会话是安全的。它已在生产场景中进行了重负载测试
快速入门
前提条件
- Go 1.24+
- 对 Prometheus 服务器的访问权限（本地或远程）
快速开始
-
克隆并构建项目：
git clone <repository-url> cd prometheus-mcp make build -
配置 Prometheus 连接：
创建一个
config.yaml文件：server: name: "prometheus-mcp" version: "1.0.0" transport: type: "stdio" # 或 "http" 用于远程客户端 prometheus: url: "http://localhost:9090" timeout: "30s" -
运行服务器：
# Stdio 模式（用于本地客户端如 Claude Desktop） ./bin/prometheus-mcp -config config.yaml # HTTP 模式（用于远程客户端） make run
开发
要扩展或修改 Prometheus MCP 服务器：
- Prometheus 工具实现于
internal/tools/tool_prometheus.go - 主客户端逻辑位于
internal/handlers/handlers.go - 配置结构位于
api/config_types.go
示例查询
基础监控：
up # 目标状态
prometheus_build_info # Prometheus 版本信息
rate(http_requests_total[5m]) # HTTP 请求率
资源监控：
sum by (instance) (up) # 按实例统计的目标
increase(http_requests_total[1h]) # 1 小时内的请求增量
topk(5, rate(http_requests_total[5m])) # 最高的 5 个请求率
Kubernetes 监控：
kube_pod_status_phase{phase="Running"} # 正在运行的 Pod
increase(kube_pod_container_status_restarts_total[30m]) > 5 # 重启次数大于 5 的 Pod
配置示例
🔗 远程客户端（Claude Web, OpenAI）
远程客户端如 Claude Web 与本地客户端有不同的需求。 此项目完全准备好处理 Claude Web，无需额外努力。
一般来说，如果您遵循我们的生产建议，所有远程客户端都会被覆盖 😊
[!NOTE]
请查看此处的配置 这里
💻 本地客户端（Claude Desktop, Cursor, VSCode）
本地客户端配置通常基于具有特定标准结构的 JSON 文件。例如，
Claude Desktop 可以通过修改名为 claude_desktop_config.json 的设置文件进行配置，如下所示：
Stdio 模式
如果您想使用 stdio 作为传输层，建议编译您的 Go 二进制文件，然后按以下方式配置客户端。 这在本地开发中推荐使用，因为它易于操作。
在配置客户端之前，请执行以下操作：
make build
[!IMPORTANT] 使用 Stdio 传输时，客户端和服务器之间没有保护措施，因为它们都在本地运行
// 文件：claude_desktop_config.json
{
"mcpServers": {
"stdio": {
"command": "/home/example/prometheus-mcp/bin/prometheus-mcp-linux-amd64",
"args": [
"--config",
"/home/example/prometheus-mcp/docs/config-stdio.yaml"
]
}
}
}
HTTP 模式
您可以使用 HTTP 传输启动您的 MCP 服务器。由于大多数本地客户端不支持原生连接到远程服务器，我们使用一个包 (mcp-remote) 作为预期的 stdio 和远程服务器之间的中间件，后者也本地运行。
这对于测试所有将在生产中部署的功能非常理想，因为与远程客户端相关的所有内容都可以提前测试，从而确保一切可以真正测试。
在配置客户端之前，请执行以下操作：
npm i mcp-remote && \
make run
// 文件：claude_desktop_config.json
{
"mcpServers": {
"local-proxy-remote": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:8080/mcp",
"--transport",
"http-only",
"--header",
"Authorization: Bearer ${JWT}",
"--header",
"X-Validated-Jwt: ${JWT}"
],
"env": {
"JWT": "eyJhbGciOiJSUzI1NiIsImtpZCI6..."
}
}
}
}
故障排除
常见问题
错误 401 未经授权
- 验证
auth.username和auth.password凭据 - 对于令牌，确保
auth.token有效且未过期 - 检查令牌是否具有所需的权限
错误 403 禁止访问
- 验证
org_id是否正确对应您的租户 - 确认用户是否有指定租户的权限
- 检查多租户设置中的 RBAC 设置
连接超时错误
- 增加配置中的
timeout - 验证到 Prometheus 服务器的网络连接
- 检查防火墙规则和网络策略
头部未识别
- 某些代理过滤自定义头部
- 验证您的安装支持
X-Scope-OrgId - 检查代理配置以转发头部
日志和调试
服务器提供了不同级别的结构化 JSON 日志记录：
成功初始化：
{
"level": "INFO",
"msg": "Prometheus 客户端初始化成功",
"url": "https://prometheus.company.com",
"auth_type": "basic",
"org_id": "tenant-1"
}
认证错误：
{
"level": "ERROR",
"msg": "执行 Prometheus 查询失败",
"error": "客户端错误：401 未经授权"
}
调试认证（需要 DEBUG 日志级别）：
{
"level": "DEBUG",
"msg": "向 Prometheus 请求添加了基本认证",
"username": "prometheus-user"
}
🌐 文档
有关 MCP 和相关规范的更多信息：
👉 MCP 授权要求
👉 RFC 9728
🤝 贡献
欢迎所有贡献！无论是报告 bug、提出功能建议还是提交代码——感谢您！以下是参与的方法：
▸ 打开一个问题 来报告 bug 或请求功能
▸ 提交一个拉取请求 来贡献改进
📄 许可
Prometheus MCP 在 Apache 2.0 许可证 下发布。