Name: Prometheus查询服务器
Author: app-sre

使用说明

Proms MCP服务器

一个精简的MCP（模型上下文协议）服务器，为LLM代理提供对多个Prometheus实例的透明访问，用于指标分析和SRE操作。

概述

此服务器使用现代FastMCP库实现MCP协议，允许LLM代理通过统一接口查询多个Prometheus实例。它支持普罗米修斯指标的发现、查询和分析，具有内置的安全验证和全面的可观察性。

特性

多种Prometheus支持：通过单个接口查询多个Prometheus实例
承载令牌身份验证：使用OpenShift承载令牌进行安全身份验证
安全强化：用于安全的基本PromQL查询验证
综合工具集：8个MCP工具，涵盖使用现代工具的发现、查询和分析 @tool 装饰器
可观测性：用于调试和监控的结构化日志记录
生产就绪：专为OpenShift/Kubernetes部署而设计
精益架构：无状态、最小依赖（5个核心依赖）、快速故障设计

MCP工具

发现工具

list_datasources：列出所有可用的Prometheus数据源
list_metrics：从数据源获取所有可用的度量名称
get_metric_metadata：获取特定指标的元数据

查询工具

query_instant：执行即时PromQL查询
query_range：执行范围PromQL查询

分析工具

get_metric_labels：获取特定指标的所有标签名称
get_label_values：获取特定标签的所有值
find_metrics_by_pattern：查找与正则表达式模式匹配的指标

快速开始

先决条件

Python 3.11+
紫外线用于依赖关系管理
Docker/Podman用于容器开发

地方发展

# Clone and setup
git clone <repository-url>
cd proms-mcp
make install

# 1. Login to your target cluster and get your token
oc login https://api.your-cluster.example.com:6443
export OPENSHIFT_TOKEN=$(oc whoami -t)

# 2. Create datasource config with your token
# this assumes your openshift token is valid to authenticate on prometheus
cat > local_config/datasources.yaml << EOF
datasources:
  - name: "my-prometheus"
    type: "prometheus"
    url: "https://prometheus.your-cluster.example.com"
    jsonData:
      httpHeaderName1: "Authorization"
    secureJsonData:
      httpHeaderValue1: "Bearer ${OPENSHIFT_TOKEN}"
EOF

# 3. Run the server with authentication enabled
make run-auth OPENSHIFT_API_URL=$(oc whoami --show-server)
# Or run the server without authentication - the connection to prometheus will still be authenticated
make run

# 4. Configure your MCP client (e.g. with Cursor and auth-enabled proms-mcp)
cat > .cursor/mcp.json << EOF
{
  "mcpServers": {
    "proms-mcp-local-auth": {
      "url": "http://localhost:8000/mcp/",
      "headers": {
        "Authorization": "Bearer ${OPENSHIFT_TOKEN}"
      }
    }
  }
}
EOF

集装箱开发

# Build container
podman build -t proms-mcp .

# Create datasource config (see Configuration section)
# Run with config
podman run -p 8000:8000 \
  -v ./datasources.yaml:/etc/grafana/provisioning/datasources/datasources.yaml:ro \
  proms-mcp

MCP客户端设置

光标集成

服务器支持两种身份验证模式：

开发（无身份验证）：

{
  "mcpServers": {
    "proms-mcp-dev": {
              "url": "http://localhost:8000/mcp/",
      "description": "Development server - no authentication"
    }
  }
}

生产（承载令牌认证）：

{
  "mcpServers": {
    "proms-mcp": {
      "url": "https://proms-mcp.apps.cluster.example.com/mcp",
      "headers": {
        "Authorization": "Bearer your-openshift-token-here"
      },
      "description": "Production server with OpenShift bearer token auth"
    }
  }
}

⚠️ 安全说明：从不承诺 .cursor/mcp.json 用真正的代币兑换git。它已经在里面了 .gitignore.

看 .cursor/mcp-examples.json 完整的配置示例包括：

开发和生产设置
服务帐户令牌配置
多环境配置
SSL验证场景

其他MCP客户端

服务器在以下位置通过HTTP公开MCP：

端点: POST http://localhost:8000/mcp/ （或您部署的URL）
协议：基于HTTP的JSON-RPC 2.0
内容类型: application/json
接受: application/json, text/event-stream
认证：不记名代币 Authorization 标题（当 AUTH_MODE=active)

📝 路径行为：服务器使用 /mcp/ （带尾随斜线）以避免HTTP 307重定向，这可能会在某些MCP客户端中导致身份验证问题。在客户端配置中始终使用尾随斜线。

配置

环境变量

PORT：MCP服务器端口（默认值：8000）
HEALTH_METRICS_PORT：运行状况和指标服务器端口（默认值：8080）
LOG_LEVEL：日志记录级别（默认值：INFO）
GRAFANA_DATASOURCES_PATH：数据源配置文件的路径（默认：/etc/grafana/provisioning/datasources/datasources.yaml）
QUERY_TIMEOUT：查询超时（秒）（默认值：30）

验证配置

服务器支持两种身份验证模式：

AUTH_MODE：身份验证模式(none 或 active，默认值： active)
OPENSHIFT_API_URL：OpenShift API服务器URL（承载令牌身份验证所需）
OPENSHIFT_CA_CERT_PATH：SSL验证的CA证书文件路径（可选，仅自定义证书需要）

无身份验证模式（仅用于开发）

# Explicitly disable authentication for development
AUTH_MODE=none uv run python -m proms_mcp

承载令牌身份验证模式（默认）

# Run with bearer token authentication
AUTH_MODE=active \
OPENSHIFT_API_URL=https://api.cluster.example.com:6443 \
uv run python -m proms_mcp

# if you're authenticated on openshift already:
AUTH_MODE=active \
OPENSHIFT_API_URL=$(oc whoami --show-server) \
uv run python -m proms_mcp

# For self-signed certificates, you can provide the CA certificate (if needed for custom certificates):
OPENSHIFT_CA_CERT_PATH=/path/to/ca.crt uv run python -m proms_mcp

身份验证实现： 服务器使用带有自我验证的Kubernetes TokenReview API来验证OpenShift承载令牌。每个用户的令牌都会自我验证，不需要特殊的RBAC权限。身份验证由自定义处理 TokenReviewVerifier 它与FastMCP的身份验证系统集成。

数据源配置

创建Grafana数据源配置YAML文件。仅 type: "prometheus" 数据源被处理。

示例数据源.yaml：

apiVersion: 1
prune: true
datasources:
  - name: "prod-prometheus"
    type: "prometheus"
    url: "https://prometheus-prod.example.com"
    access: "proxy"
    editable: false
    jsonData:
      httpHeaderName1: "Authorization"
    secureJsonData:
      httpHeaderValue1: "Bearer prod-token"
  - name: "demo-prometheus"
    type: "prometheus"
    url: "https://demo.robustperception.io:9090"
    access: "proxy"
    editable: false

安全

PromQL查询验证

服务器执行基本的安全检查：

查询长度：限制为10000个字符
空查询：防止空查询或仅空格查询
输入消毒：通过httpx进行基本参数编码

API终点

POST/mcp/：MCP JSON-RPC 2.0端点（端口8000）
GET/健康：健康检查（端口8080）
GET/指标：普罗米修斯指标（端口8080）

部署

OpenShift部署

使用提供的OpenShift模板进行部署：

# Development deployment (no authentication)
oc process -f openshift/deploy.yaml \
  -p IMAGE=quay.io/app-sre/proms-mcp \
  -p IMAGE_TAG=latest \
  -p AUTH_MODE=none \
  | oc apply -f -

# Production deployment (bearer token authentication)
oc process -f openshift/deploy.yaml \
  -p IMAGE=quay.io/app-sre/proms-mcp \
  -p IMAGE_TAG=v1.0.0 \
  -p AUTH_MODE=active \
  -p OPENSHIFT_API_URL=https://api.cluster.example.com:6443 \
  | oc apply -f -

# No additional RBAC setup is needed - the server uses self-validation

模板参数：

AUTH_MODE: none （开发）或 active （生产，默认）
OPENSHIFT_API_URL：OpenShift API服务器URL（默认值： https://kubernetes.default.svc 集群内）
OPENSHIFT_CA_CERT_PATH：CA证书路径（默认：在群集服务帐户CA中）
NAMESPACE：目标命名空间（必需）
HOSTNAME：路由主机名（必填）

MCP客户端配置

开发模式（无身份验证）

{
  "mcpServers": {
    "proms-mcp-dev": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

生产模式（承载令牌）

{
  "mcpServers": {
    "proms-mcp": {
      "url": "https://proms-mcp.apps.cluster.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${OPENSHIFT_TOKEN}"
      }
    }
  }
}

获取您的OpenShift令牌：

export OPENSHIFT_TOKEN=$(oc whoami -t)

RBAC要求

对于生产（承载令牌身份验证）部署：

服务帐户: proms-mcp-server （由模板创建）-仅用于pod标识
不需要特殊的RBAC权限：服务器使用自我验证，每个用户的令牌都会自我验证
用户令牌：用户需要有效的OpenShift令牌(oc whoami -t)

该模板为pod标识创建ServiceAccount。由于身份验证使用自验证，因此不需要ClusterRoleBinding或特殊权限。

发展

代码质量

make format          # Format code and fix imports
make lint            # Lint and type check code
make test            # Run tests with coverage

项目结构

proms-mcp/
  proms_mcp/             # Main package
    auth.py                # TokenReview-based authentication with FastMCP integration
    server.py              # FastMCP server with 8 MCP tools
    client.py              # Prometheus API wrapper
    config.py              # Config parser with auth support
    monitoring.py          # Health/metrics endpoints  
    logging.py             # Structured logging configuration
  tests/                   # Test suite (mirrors package structure)
  openshift/deploy.yaml    # OpenShift template with RBAC support
  local_config/            # Local development configuration

故障排除

常见问题

未加载数据源:
- 检查一下 GRAFANA_DATASOURCES_PATH 指向您的数据源文件
- 验证YAML语法是否有效（也支持JSON格式）
- 确保文件包含 datasources 阵列与 type: "prometheus" 条目
- 使用 make run 它会自动将路径设置为 local_config/datasources.yaml
身份验证失败：验证中的承载令牌 secureJsonData
查询超时：调整 QUERY_TIMEOUT 环境变量
查询验证错误：检查查询长度并确保查询非空
客户端连接问题:
- 400错误请求：服务器重新启动-客户端将自动重新连接
- 406不可接受：客户必须接受 application/json, text/event-stream

调试模式

LOG_LEVEL=DEBUG make run

健康检查

curl http://localhost:8080/health
curl http://localhost:8080/metrics | grep mcp_

文档

SPECS.md -技术规范和架构
法学硕士 -AI助手开发指南
测试.md -带有承载令牌示例的本地测试指南

贡献

分叉存储库
创建要素分支
通过测试进行更改
运行质量检查： make format lint test
提交拉取请求

许可证

Apache许可证2.0