内容
<!-- mcp-name: io.github.rex/rancher-mcp -->
<p align="center">
<img src="https://raw.githubusercontent.com/rex/mcp-rancher/main/docs/assets/header.png" alt="MCP Rancher — 面向 AI 辅助的 Rancher 操作的能力感知控制平面" />
</p>
<p align="center">
<a href="https://github.com/rex/mcp-rancher/actions/workflows/validate.yml"><img src="https://img.shields.io/github/actions/workflow/status/rex/mcp-rancher/validate.yml?branch=main&label=CI" alt="CI" /></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-server-2b6cd0" alt="MCP 服务器" /></a>
<a href="docs/tool-manifest.json"><img src="https://img.shields.io/badge/tools-321-2b6cd0" alt="321 个工具" /></a>
<a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.12%2B-3776ab?logo=python&logoColor=white" alt="Python 3.12+" /></a>
<a href="https://github.com/microsoft/pyright"><img src="https://img.shields.io/badge/types-pyright%20strict-blue" alt="Pyright 严格类型检查" /></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT 许可证" /></a>
</p>
<p align="center">
通过任何 MCP 客户端操作 Rancher 管理的 Kubernetes —
发现、通用资源访问和精选操作工作流，
封装在审计日志、速率限制、确认保护的安全模型中。
</p>
<p align="center">
<a href="#快速开始">快速开始</a> ·
<a href="#工具表面">工具表面</a> ·
<a href="#架构">架构</a> ·
<a href="#安全模型">安全模型</a> ·
<a href="#兼容性">兼容性</a> ·
<a href="#开发">开发</a>
</p>
---
## 为什么存在
Rancher 是实际使用的 Kubernetes 集群管理工具 — 它支持 **两个 API** （旧的 Norman `/v3` 平面和现代的 Steve `/v1` 平面），版本不同，集群后面都有自己的代理。直接将通用的 Kubernetes MCP 服务器指向 Rancher 会忽略 Rancher 特有的功能；将代理指向原始 `kubectl` 会放弃审计能力、防护措施和整个管理平面视图。
**MCP Rancher** 是为此而设计的：
- **能力感知，而不是版本天真**。它检测每个连接的 Rancher 实际支持的功能，而不是假设。一个二进制文件涵盖 **2.6.5 → 2.9.3**，具有相同的工具表面。
- **多实例优先**。实验室、预发布、生产 — 配置它们；标记生产 `read_only: true`，每个变更都在配置层被拒绝，在任何防护措施触发之前。
- **无所不能**。精选工具涵盖 95% 的常见操作；通用引擎可以访问 **每个** 资源，无论哪个 API 平面暴露 — 甚至是尚未编写工具的类型。
## 工具表面
**321 个工具：178 个只读 · 143 个写入 · 38 个破坏性** — 从注册表本身计算，而不是手动计数。 [`docs/tool-manifest.json`](docs/tool-manifest.json) 是 **从实时 FastMCP 注册表生成的** （`make tool-manifest`），如果它与代码有偏差，CI 门控会失败构建。每个工具的描述、安全注释和参数都存储在那里；叙述性注册表带有切片跟踪的是 [`docs/tool-catalog.md`](docs/tool-catalog.md)。
| 层级 | 功能 | 示例 |
|---|---|---|
| **发现和模式** | 探索任何实例的能力 | `rancher_server_version`、`rancher_norman_schema_list`、`rancher_capability_domain_list` |
| **通用引擎** | CRUD + 操作 + 链接 + 监听任意资源，两个平面 | `rancher_steve_resource_list`、`rancher_norman_resource_action_invoke`、`rancher_steve_resource_watch` |
| **精选读取** | 类型化、格式化的响应，涵盖约 25 个领域 | `rancher_pods_list`、`rancher_deployments_list`、`rancher_longhorn_volumes_list`、`rancher_policy_reports_list` |
| **精选写入** | 防护措施下的变更 | `rancher_deployment_scale`、`rancher_deployment_restart`、`rancher_cron_job_suspend`、`rancher_node_cordon`、`rancher_secret_create` |
| **操作汇总** | 一键式诊断 | `rancher_cluster_health_check`、`rancher_find_failing_pods`、`rancher_find_stalled_rollouts`、`rancher_project_health_summary` |
涵盖的领域：集群和节点 · 项目和命名空间 · 工作负载 · Pod 和服务 · 存储 · 网络 · 配置和密钥 *(值被屏蔽)* · 证书 *(密钥被屏蔽)* · RBAC · 身份验证和身份 · 应用和目录 · 日志管道 · Prometheus 监控 · 策略报告 · CIS 合规性 · 备份操作 · etcd 备份 · Longhorn · Fleet · 配置 · 设置和功能 · 警报和通知。
## 快速开始
### 要求
- Python 3.12+ 和 [uv](https://docs.astral.sh/uv/)
- Rancher API 令牌 ([创建令牌](https://ranchermanager.docs.rancher.com/reference-guides/user-settings/api-keys))
### 安装和运行
```bash
# 从源码
git clone https://github.com/rex/mcp-rancher.git
cd mcp-rancher
make setup # 依赖项、.env 脚手架、预提交钩子
cp .env.example .env # 设置 RANCHER_URL 和 RANCHER_TOKEN
make dev # 运行 MCP 服务器（标准输入/输出）
```
一旦发布到 PyPI，就可以使用一行命令安装：`uvx rancher-mcp`。
### Claude 代码
```bash
claude mcp add rancher \
-e RANCHER_URL=https://rancher.example.com \
-e RANCHER_TOKEN=token-xxxxx:yyyyyyyyy \
-- uv run --directory /path/to/mcp-rancher rancher-mcp
```
### Claude 桌面
```json
{
"mcpServers": {
"rancher": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-rancher", "rancher-mcp"],
"env": {
"RANCHER_URL": "https://rancher.example.com",
"RANCHER_TOKEN": "token-xxxxx:yyyyyyyyy"
}
}
}
}
```
### 多个实例
```env
RANCHER_INSTANCES_JSON='{
"production": {"url": "https://rancher.prod.example.com", "token": "token-a:xxx", "verify_ssl": true, "read_only": true},
"lab": {"url": "https://rancher.lab.example.com", "token": "token-b:yyy", "verify_ssl": false, "read_only": false}
}'
RANCHER_DEFAULT_INSTANCE=production
```
每个工具都接受一个可选的 `instance` 参数。标记为 `read_only: true` 的实例会拒绝 **所有** 变更，在设置层。
## 架构
```mermaid
flowchart LR
A[MCP 客户端<br/>Claude 代码 · Claude 桌面 · 任意] -- 标准输入/输出 --> S
subgraph S[rancher-mcp]
direction TB
L1[发现和模式<br/>平面 · 模式 · 能力]
L2[通用引擎<br/>任意资源 · 两个平面<br/>CRUD · 操作 · 链接 · 监听]
L3[精选工具<br/>类型化模型 · 格式化输出<br/>下一步提示]
G[安全层<br/>只读防护 · 确认短语<br/>审计日志 · 速率限制 · 屏蔽]
L1 --> L2 --> L3
L3 --> G
L2 --> G
end
G -- Norman /v3 --> R1[(Rancher<br/>实例 A)]
G -- Steve /v1 + k8s 代理 --> R1
G -- Norman + Steve --> R2[(Rancher<br/>实例 B)]
```
三个层级，刻意分离：**发现** 告诉你实例能做什么，**通用引擎** 可以操作它暴露的任何东西，**精选工具** 使常见路径类型化、格式化并自我描述（每个响应都带有 `suggested_next_steps`）。大多数精选工具都是 **从 YAML 描述符** （`catalog/curated_tools/`）生成的，并带有漂移门控 — 编辑决策存储在描述符中，而不是样板。
## 安全模型
为代理指向的集群支付薪水的那一天而构建：
| 防护措施 | 行为 |
|---|---|
| **只读实例** | `read_only: true` 拒绝该实例的所有变更，在工具逻辑运行之前 |
| **破坏性确认** | 删除需要显式输入短语（例如 `"delete steve namespace foo"`）— 没有短语，不删除 |
| **工具注释** | 每个工具都声明 `readOnlyHint` / `destructiveHint` / `idempotentHint`，客户端可以根据它们设置 UX |
| **审计日志** | 每个变更都会发出结构化的 `event="audit"` 记录 — 工具、操作、平面、实例、资源、结果。参数 **名称** 仅限；值从不记录 |
| **速率限制** | 写入的令牌桶（默认 60/分钟）— 失控的循环无法用 API 轰炸 |
| **密钥和证书屏蔽** | 密钥值和证书私钥在结构上从精选响应中缺失（显式通用工具选择加入后公开） |
| **结构化错误** | 防护措施拒绝返回类型化的 `error_code` 信封，代理可以根据它们分支 — 而不是原始字符串 |
## 兼容性
| | |
|---|---|
| **主要目标** | Rancher **2.9.3** （生产验证） |
| **兼容性底线** | Rancher **2.6.5** （通过能力检测保持绿色） |
| **API 平面** | Norman `/v3` + Steve `/v1` (+ 每个集群的 Kubernetes 代理) |
| **传输** | 标准输入/输出 |
能力检测在运行时桥接版本差异 — 没有版本固定的构建，没有“在我 Rancher 上有效”。两个目标都经过相同的测试套件验证，读取路径已针对 2.6.5 实验室和 2.9.3 生产集群进行实时验证 ([验证报告](docs/live-validation-2026-05-06.md))。
## 配置
| 变量 | 默认值 | 用途 |
|---|---|---|
| `RANCHER_URL` | — | Rancher 服务器 URL（单实例模式） |
| `RANCHER_TOKEN` | — | API 令牌 (`token-xxxxx:yyyyyyyyy`) |
| `RANCHER_VERIFY_SSL` | `true` | TLS 验证 |
| `RANCHER_INSTANCES_JSON` | — | 多实例配置（参见上文） |
| `RANCHER_DEFAULT_INSTANCE` | 定义的第一个 | 调用工具时未命名的实例 |
| `RANCHER_MCP_SERVER_NAME` | `rancher-mcp` | 客户端宣布的服务器身份 |
| `RANCHER_MCP_SERVER_DESCRIPTION` | 内置 | 客户端宣布的服务器描述 |
| `RANCHER_MCP_WRITE_RATE_LIMIT_PER_MIN` | `60` | 写入速率限制（`0` 禁用） |
## 项目状态
用于 **读取、诊断和防护措施** 操作的运输和稳定。诚实的账本记录了超出此范围的内容：
- **破坏性工作流** （节点排水、etcd/备份恢复、证书轮换、集群升级/删除）是 **路线图** — 故意在实际 **读取路径** 里程碑之后进行。通用引擎 + 确认防护已经涵盖了这些用例，供需要它们的运营商今天使用。
- Alertmanager 路由/静默表面需要集群内 API 集成，目前暂缓。
- 完整的按版本兼容性矩阵（Track G）正在进行中； [第一次实时验证运行](docs/live-validation-2026-05-06.md) 涵盖了两个目标上的读取矩阵。
工作跟踪到工具级别： [`docs/tool-catalog.md`](docs/tool-catalog.md) （每个工具一行，每个空白一个切片 ID）和 [`ROADMAP.md`](ROADMAP.md)。
## 开发
```bash
make help # 每个目标都有文档
make validate # 代码生成漂移 + 清单漂移 + 架构 + lint + 类型检查 + 测试
make tool-manifest # 从注册表重新生成 docs/tool-manifest.json
make lab-up # 本地 Rancher 2.6.5 实验室（kind + helm），全脚本化
make integration-current # 隔离的 Rancher 2.14.3 端到端测试运行
make live-read-matrix # 读取验证探针针对配置的实例
make mock-rancher # 固定备份的模拟 Rancher，用于提供程序配置测试
```
- **本地实验室** — 自包含的 Rancher 2.6.5 在 kind 上，带有模拟的下游集群；存储库本地 kubeconfigs，从不触摸您的机器状态。
- **当前集成实验室** — Rancher 2.14.3 在单独的 Kind 集群和端口 `9443` 上；使用 `make integration-current` 串行运行，以避免与旧实验室重叠的 Docker 资源需求。
- **合约固件** — 从实时 Rancher 提交的固件存储在 `tests/fixtures/` 下；`respx` 在测试中固定 HTTP 界限。
- **代码生成** — 精选工具从 `catalog/curated_tools/*.yml` 描述符中发出；`make check-codegen` 在漂移时失败。
- **门控** — ruff、pyright 严格、624 个测试覆盖率下限、架构行限制、模块形状检查、机密扫描。所有门控都失败关闭，所有门控都连接到 pre-commit。
堆栈：Python 3.12 · [FastMCP](https://github.com/modelcontextprotocol/python-sdk) · [httpx](https://www.python-httpx.org/) · [Pydantic v2](https://docs.pydantic.dev/) · [structlog](https://www.structlog.org/) · [uv](https://docs.astral.sh/uv/)
## 安全
参见 [SECURITY.md](SECURITY.md) 获取威胁模型、令牌指导和漏洞报告方法。
## 许可证
[MIT](LICENSE)
