# monitoring-mcp-server

**Repository Path**: yanxi-mcp/monitoring-mcp-server

## Basic Information

- **Project Name**: monitoring-mcp-server
- **Description**: monitoring-mcp-server
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-01
- **Last Updated**: 2026-10-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Monitoring MCP Server

基于 Python MCP SDK v2 的只读监控服务，通过 stdio 向 AI 客户端提供多集群监控工具。支持 Prometheus、Grafana、Kubernetes API 和 Loki；任何数据源均需由运维人员显式配置，服务不会自行取得凭据。

## 功能

| 工具 | 功能 |
| --- | --- |
| `list_clusters` | 查看已配置集群、允许访问的 Namespace 和数据源 |
| `server_status` | 汇总 Pod 阶段和 Prometheus `up` 样本 |
| `query_metrics` | 查询 CPU、内存和磁盘的预设 PromQL |
| `analyze_metrics` | 列出指标最高的样本、单位和核查建议 |
| `list_pods` | 分页查看 Pod 状态和容器重启原因 |
| `diagnose_pods` | 根据 Pod 状态给出候选原因和建议 |
| `search_logs` | 按文本分页搜索 Loki 日志，并脱敏返回 |
| `list_dashboards` / `get_dashboard` | 按 Namespace 对应的 Grafana 文件夹查看仪表盘和面板元数据 |
| `analyze_alerts` | 查看活跃告警并按事件去重 |
| `root_cause` | 关联 Pod 异常与活跃告警，区分事实和推断 |

诊断建议只提供排查方向，不会执行修复、重启、变更配置或发送通知。`root_cause` 的关联结果并不证明因果关系。

## 安装与启动

要求 Python 3.12 或 3.13。建议安装 `uv`，在本目录执行：

```powershell
uv sync --extra dev
Copy-Item config.example.json config.local.json
# 编辑 config.local.json，并将每个 *_token_env 指向已有的只读凭据环境变量。
$env:MONITORING_DEV_PROMETHEUS_TOKEN = '<read-only-token>'
$env:MONITORING_DEV_GRAFANA_TOKEN = '<read-only-token>'
$env:MONITORING_DEV_KUBERNETES_TOKEN = '<read-only-token>'
$env:MONITORING_DEV_LOKI_TOKEN = '<read-only-token>'
uv run monitoring-mcp --config config.local.json
```

示例中的地址、Grafana 文件夹 UID 和令牌名称必须按实际环境调整。没有某个数据源时，可删去相应的 `*_url` 和 `*_token_env`，对应工具调用会明确报未配置。支持在 `clusters` 下加入 `test`、`prod` 等环境；每次调用必须明确传入集群名和 Namespace。

MCP 客户端配置示例：

```json
{
  "mcpServers": {
    "monitoring": {
      "command": "D:/python_workplace/monitoring-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "monitoring_mcp.main", "--config", "D:/python_workplace/monitoring-mcp/config.local.json"]
    }
  }
}
```

MCP 客户端启动进程时必须继承上述令牌环境变量。正式环境请使用机密管理器注入凭据，不要把令牌写进 JSON、命令行参数、Git 或日志。`ca_file` 可选；如使用私有 CA，填写可读取的 PEM 文件路径。远端数据源仅允许 HTTPS，本机调试可使用 localhost HTTP。

## 最小权限与查询范围

- Prometheus / Loki：只读查询端点；Grafana：仅授予所需文件夹的仪表盘查看权限；Kubernetes：对允许的 Namespace 授予 `pods` 的 `get`、`list` 权限，不需要 Secret 或写权限。
- `namespaces` 是每个集群的白名单。不要将生产和测试环境指向同一个高权限令牌。
- PromQL 仅支持 `cpu`、`memory`、`disk`、`up`、`alerts` 五个内置键。开放给 AI 的 `query_metrics` 仅接受前三个键。
- `list_pods` 每页最多 100 条，响应中的 `next_cursor` 可继续翻页。状态和诊断最多读取 10 页（1000 个 Pod），达到上限时 `truncated=true`，所有计数均为已读取范围内的部分结果。
- 日志时间窗为 1–24 小时、每页最多 100 行且每行截断至 2000 字符。返回的 `next_cursor` 可用于继续向前翻页，后续调用须保持集群、Namespace、搜索文本和时间窗一致。游标必须仍在所选时间窗内；同一时间戳的翻页最多查询 1000 行，超过时会明确报错。数据源响应体上限 2 MB，指标和仪表盘查询有短时内存缓存。
- Pod 输出仅包含名称、Namespace、阶段、容器重启次数及状态代码，不返回环境变量、镜像拉取密钥和容器状态消息。Grafana 仅返回标题、UID、链接及面板标题。
- Grafana 的 `grafana_folders` 将每个允许的 Namespace 映射到可见文件夹 UID；未配置映射时会拒绝查询。搜索和单个仪表盘读取均检查文件夹归属。仍应让 Grafana 服务账号本身只拥有相应文件夹的读取权限。
- 查询审计记录写入 stderr，仅含操作、集群、允许的 Namespace、授权判断、数据源、HTTP 方法、状态和缓存命中信息；不记录令牌、查询内容或原始日志。

Prometheus 需采集容器 CPU / 内存、PVC 用量和 `ALERTS` 等相应指标，否则对应工具可能返回空样本。`up{namespace=...}` 要求目标带 `namespace` 标签；若未配置该标签，`server_status` 的 `up_series` 为空，此时仍能看到 Pod 阶段。磁盘指标是已用字节数，不能单凭该值判断磁盘压力。

`server_status` 和 `root_cause` 同时依赖 Kubernetes 与 Prometheus；若其中一个数据源未配置，工具会返回明确错误。诊断和状态统计超过 1000 个 Pod 时只表示已读取的部分范围。

Grafana 文件夹过滤使用 [Grafana Search API 的 `folderUIDs` 参数](https://grafana.com/docs/grafana/latest/developer-resources/api-reference/http-api/api-legacy/folder_dashboard_search/)。

## 验证

```powershell
uv run --extra dev pytest -q
uv run --extra dev ruff check .
uv run --extra dev ruff format --check .
```

离线测试使用本地模拟 HTTP 响应，不需要真实监控后端。上线前需在目标环境验证 API 路径、实际指标名称、Grafana 权限、Kubernetes RBAC、证书链和真实日志标签。