使用说明

普罗米修斯MCP

一个生产就绪的MCP（模型上下文协议）服务器，带有集成的Prometheus客户端，通过MCP协议实现无缝的PromQL查询。直接从Claude、OpenAI等人工智能助手执行Prometheus查询、分析指标并监控您的基础设施。

建于 mcp锻造厂 🔧
本项目基于优秀的MCP服务器模板 @乙酰胆碱酯酶，它提供了现成的生产就绪OAuth身份验证、JWT验证和企业级功能。

动机

监控和可观察性对于现代应用程序至关重要，但从AI助手访问Prometheus指标需要一个无缝集成层。这个MCP服务器弥合了这一差距，允许您通过与AI工具的自然语言交互直接查询Prometheus，使监控更容易访问和直观。

特性

🔍 完成指标集成
- 使用以下命令执行即时PromQL查询 prometheus_query
- 使用执行范围查询 prometheus_range_query
- 列出所有可用指标 prometheus_list_metrics
- 通过查询任何配置的后端 backend 参数
🔌 多后端支持
- 配置多个指标后端（普罗米修斯、PMM、灭霸、维多利亚指标等）
- 在查询时使用单个参数在后端之间切换
- 只需YAML配置即可添加新的后端，无需更改代码
🔐 企业身份验证支持
- HTTP基本认证
- 承载令牌认证（JWT/neneneba API令牌）
- 多租户支持 X-Scope-OrgId 头球
🏢 多平台兼容性
- 香草普罗米修斯实例
- Cortex多租户设置
- Thanos查询部署
- Grafana云集成
- PMM（Percona监测和管理）
- 具有自定义标头的企业代理
🛡️ 生产就绪安全
- 符合OAuth RFC 8414和RFC 9728
- JWT验证（委托或本地JWKS）
- 可配置的访问日志，带有字段排除/编辑功能
🚀 基础设施功能
- Docker容器化就绪
- Kubernetes部署的Helm Chart
- 结构化JSON日志记录
- 全面的错误处理和故障排除

后端配置

所有指标后端都配置在 backends 钥匙就像一张地图。每个条目的键都将成为查询中使用的后端名称。

基本设置

backends:
  prometheus:
    url: "http://localhost:9090"

多个后端

backends:
  prometheus:
    url: "http://localhost:9090"
    org_id: "tenant-1"
    available_orgs:
      - tenant-1
      - tenant-2

  pmm:
    url: "http://pmm:8080/prometheus"
    auth:
      type: "basic"
      username: "admin"
      password: "${PMM_PASSWORD}"

  thanos:
    url: "http://thanos-query:9090"
    auth:
      type: "token"
      token: "${THANOS_TOKEN}"

认证

每个后端都独立支持自己的身份验证：

使用环境变量（建议保密）

backends:
  prometheus:
    url: "https://prometheus.example.com"
    org_id: "tenant-1"
    auth:
      type: "basic"
      username: "prometheus-user"
      password: "${PROMETHEUS_PASSWORD}"

两者 ${VAR} 和 $VAR 支持语法。在启动服务器之前设置环境变量：

export PROMETHEUS_PASSWORD="secret-password"
./prometheus-mcp --config config.yaml

承载令牌配置

backends:
  grafana-cloud:
    url: "https://prometheus.grafana.net/api/prom"
    auth:
      type: "token"
      token: "${GRAFANA_TOKEN}"

后端配置选项

url （必填）：度量服务器URL
org_id （可选）：值 X-Scope-OrgId 标头，适用于多租户设置
available_orgs （可选）：可用租户列表（显示在工具说明中）
auth.type （可选）：身份验证类型
- "basic"：HTTP基本身份验证
- "token"：承载令牌身份验证
- 空或未指定：无身份验证
auth.username 和 auth.password：基本身份验证凭据
auth.token：用于承载身份验证的令牌

常见用例

Prometheus香草（无身份验证）

backends:
  prometheus:
    url: "http://localhost:9090"

Cortex多租户

backends:
  cortex:
    url: "http://cortex-gateway:8080/prometheus"
    org_id: "tenant-acme"
    auth:
      type: "basic"
      username: "cortex-user"
      password: "cortex-pass"

带有租户标题的Thanos查询

backends:
  thanos:
    url: "http://thanos-query:9090"
    org_id: "team-backend"

带API代币的Grafana云

backends:
  grafana-cloud:
    url: "https://prometheus.grafana.net/api/prom"
    auth:
      type: "token" 
      token: "glc_eyJrIjoiN3..."

PMM（Percona监测和管理）

backends:
  pmm:
    url: "http://pmm.example.com:8080/prometheus"
    auth:
      type: "basic"
      username: "admin"
      password: "${PMM_PASSWORD}"

多租户支持

普罗米修斯MCP支持 动态多租户查询，允许您按需查询不同的租户，而无需重新启动服务器。

配置

集合A 默认租户 和列表 可用租户 在后端配置中：

backends:
  prometheus:
    url: "http://mimir-gateway:8080/prometheus"
    org_id: "my-company"
    available_orgs:
      - my-company
      - my-company-slo
      - my-company-dev

当 available_orgs 配置后，AI代理将在工具描述中看到这些选项：

org_id: Optional tenant ID for multi-tenant Prometheus/Mimir. 
        Default: 'my-company'. 
        Available tenants: [my-company, my-company-slo, my-company-dev].

按查询租户覆盖

使用以下命令覆盖特定查询的租户 org_id 参数：

{
  "backend": "prometheus",
  "query": "http_requests_total",
  "org_id": "my-company-slo"
}

行为

默认租户：用途 org_id 如果不是，则从配置 org_id 在查询中提供
明确租户：用途 org_id 从查询参数中重写配置
无租户：如果配置和查询都不提供 org_id，没有 X-Scope-OrgId 发送标头
非多租户后端：如果 org_id 是为后端提供的，没有 org_id 或 available_orgs 在其配置（例如PMM）中 X-Scope-OrgId 标头仍在发送，但可能会被服务器忽略。在这种情况下会记录警告

可用的MCP工具

所有工具都接受 backend 参数，指定要查询哪个配置的后端。如果只配置了一个后端，则默认使用它。

1. `prometheus_query`

对指标后端执行即时PromQL查询。

参数：

backend （如果是单个后端，则可选）：要查询的后端的名称
query （必填）：要执行PromQL查询
time （可选）：RFC3339格式的时间戳。如果未提供，则使用当前时间
org_id （可选）：多租户设置的租户ID。从配置中覆盖默认租户

例子：

{
  "backend": "prometheus",
  "query": "up",
  "time": "2024-01-15T10:30:00Z"
}

查询PMM：

{
  "backend": "pmm",
  "query": "mysql_global_status_threads_connected"
}

2. `prometheus_range_query`

对指标后端执行PromQL范围查询。

参数：

backend （如果是单个后端，则可选）：要查询的后端的名称
query （必填）：要执行PromQL查询
start （必填）：RFC3339格式的开始时间
end （必填）：RFC3339格式的结束时间
step （可选）：步长（例如“30s”、“1m”、“5m”）。默认为“1m”
org_id （可选）：多租户设置的租户ID。从配置中覆盖默认租户

例子：

{
  "backend": "prometheus",
  "query": "rate(http_requests_total[5m])",
  "start": "2024-01-15T10:00:00Z",
  "end": "2024-01-15T11:00:00Z",
  "step": "1m"
}

3. `prometheus_list_metrics`

列出指标后端的所有可用指标。

参数：

backend （如果是单个后端，则可选）：要查询的后端的名称
query （可选）：用于过滤指标的Glob模式（例如，“redis*”、“中央处理器')
org_id （可选）：多租户设置的租户ID。从配置中覆盖默认租户
limit （可选）：要返回的最大指标数。默认值为100
offset （可选）：分页时要跳过的指标数。默认值为0

例子：

{
  "backend": "prometheus",
  "query": "http_*"
}

示例响应：

{
  "total_metrics": 245,
  "returned": 100,
  "offset": 0,
  "limit": 100,
  "has_more": true,
  "metrics": [
    "up",
    "prometheus_build_info",
    "http_requests_total"
  ]
}

部署

生产🚀

使用位于 chart/ 目录。

我们对生产中的远程服务器的建议：

使用MCP会话时，在MCP服务器前使用一致的哈希HTTP代理
使用在MCP前执行JWT验证的HTTP代理，而不是使用附带的中间件：
- 以与我们的中间件完全相同的方式保护您的MCP，但使用经过超级测试和可扩展的代理
- 改进您的开发体验，因为您不必做任何事情，只需开发您的MCP工具即可
使用符合以下条件的OIDP：
- 封面Oauth动态客户端注册
- 能够自定义您的JWT索赔。

👉 钥匙斗篷涵盖了Oauth2方面所需的一切

👉 伊斯蒂奥涵盖了在MCP前验证JWT所需的所有内容

👉 哈希路由器使用可配置且真正一致的哈希环来路由流量，因此您的会话是安全的。它已经在生产场景中的重负载下进行了测试

入门指南

先决条件

转到1.24+
访问兼容Prometheus的度量服务器（本地或远程）

快速开始

克隆并构建项目：

git clone <repository-url>
cd prometheus-mcp
make build

配置后端：

创建一个 config.yaml 文件：

server:
  name: "prometheus-mcp"
  version: "1.0.0"
  transport:
    type: "stdio"  # or "http" for remote clients

backends:
  prometheus:
    url: "http://localhost:9090"

运行服务器：

./bin/prometheus-mcp -config config.yaml

发展

要扩展或修改Prometheus MCP服务器：

工具处理程序在 internal/tools/tool_prometheus_*.go
后端客户端逻辑在 internal/handlers/handlers.go
配置结构如下 api/config_types.go

查询示例

基本监测：

up                                    # Target status
prometheus_build_info                 # Prometheus version info
rate(http_requests_total[5m])         # HTTP request rate

资源监控：

sum by (instance) (up)                        # Up targets by instance
increase(http_requests_total[1h])              # Request increase over 1h
topk(5, rate(http_requests_total[5m]))         # Top 5 highest request rates

Kubernetes监控：

kube_pod_status_phase{phase="Running"}         # Running pods
increase(kube_pod_container_status_restarts_total[30m]) > 5  # Pods with >5 restarts

配置示例

🔗 远程客户端（Claude Web、OpenAI）

像Claude Web这样的远程客户端与本地客户端有不同的要求。这个项目已经完全准备好与Claude Web打交道，您无需付出任何努力。

一般来说，如果您遵循我们的生产建议，所有远程客户端都会被覆盖😊

[！注意]
嘿！查看配置这里

💻 本地客户端（克劳德桌面、光标、VSCode）

本地客户端配置通常基于具有特定标准结构的JSON文件。例如， Claude Desktop可以通过修改名为的设置文件进行配置 claude_desktop_config.json 包括以下部分：

标准模式

如果你想使用stdio作为传输层，建议编译Go二进制文件，然后配置客户端如下所述。这在当地开发中是推荐的，因为它很容易使用。

在配置客户端之前，请执行以下操作：

make build

[！重要] 使用Stdio传输时，客户端和服务器之间没有保护，因为它们都在本地运行

// file: 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

// file: 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 由您的安装支持
检查标头转发的代理配置

未知后端错误

验证 backend 参数与您的 backends 配置
检查后端URL是否可访问
验证服务器日志中的后端是否已正确初始化

日志记录和调试

服务器提供不同级别的结构化JSON日志记录：

初始化成功：

{
  "level": "INFO",
  "msg": "Backend client initialized",
  "backend": "prometheus",
  "url": "https://prometheus.company.com",
  "auth_type": "basic",
  "org_id": "tenant-1"
}

身份验证错误：

{
  "level": "ERROR", 
  "msg": "failed to execute query on backend \"prometheus\"",
  "error": "client error: 401 Unauthorized"
}

调试身份验证（需要Debug日志级别）：

{
  "level": "DEBUG",
  "msg": "Added basic auth to request", 
  "backend": "prometheus",
  "username": "prometheus-user"
}

🌐 文档

有关MCP和相关规范的更多信息：

👉 MCP授权要求

👉 RFC 9728

👉 MCP Go文档

👉 mcp远程包

👉 Prometheus查询文档

🤝 贡献

欢迎所有捐款！无论您是报告错误、建议功能还是提交代码——谢谢！以下是如何参与其中：

▸ 打开一个问题报告错误或请求功能

▸ 提交拉取请求促进改进

📄 许可证

Prometheus MCP根据 Apache 2.0许可证.

使用说明

普罗米修斯MCP

动机

特性

后端配置

基本设置

多个后端

认证

使用环境变量（建议保密）

承载令牌配置

后端配置选项

常见用例

Prometheus香草（无身份验证）

Cortex多租户

带有租户标题的Thanos查询

带API代币的Grafana云

PMM（Percona监测和管理）

多租户支持

配置

按查询租户覆盖

行为

可用的MCP工具

1. prometheus_query

2. prometheus_range_query

3. prometheus_list_metrics

部署

生产🚀

入门指南

先决条件

快速开始

发展

查询示例

配置示例

🔗 远程客户端（Claude Web、OpenAI）

💻 本地客户端（克劳德桌面、光标、VSCode）

标准模式

HTTP模式

故障排除

常见问题

错误401未经授权

错误403禁止

连接超时错误

无法识别标题

未知后端错误

日志记录和调试

🌐 文档

🤝 贡献

📄 许可证

相关 MCP

Prometheus数据访问服务器

Signoz MCP服务器

Zabbix API服务

AI代理工具集成层

Prometheus MCP服务器

Prometheus模型上下文协议服务器

1. `prometheus_query`

2. `prometheus_range_query`

3. `prometheus_list_metrics`