rancher-mcp

通过任意 MCP 客户端管理 Rancher 托管的 Kubernetes — 发现、通用资源访问和精选的运维工作流， 并采用带审计日志、速率限制和确认保护的安全模型。

快速开始 · 工具概览 · 架构 · 安全模型 · 兼容性 · 开发

---

为什么要开发它

Rancher 是实际管理 Kubernetes 集群的方式 — 它提供 两套 API（旧版 Norman /v3 平面和现代 Steve /v1 平面），各版本间存在差异，并将 每个集群都置于各自的代理之后。将通用 Kubernetes MCP 服务连接到 Rancher， 会遗漏所有 Rancher 特有的功能；让 Agent 直接使用原始 kubectl，则会失去 可审计性、防护措施以及管理平面视图。

MCP Rancher 专为这种现实情况打造：

• 感知能力，而非忽视版本差异。 它会检测每个已连接的 Rancher 实际支持哪些功能，而不是一概而论。一个二进制文件即可覆盖 2.6.5 → 2.9.3，且工具集保持一致。
• 优先支持多实例。 实验环境、预发布环境、生产环境 — 全部配置；将生产环境标记为 read_only: true，配置层就会拒绝所有变更，无需触发任何防护措施。
• 触及所有资源。 精选工具覆盖常见需求的 95%；通用引擎则可访问任一 API 平面公开的 所有 资源 — 即使是尚无人为其编写工具的类型也不例外。

工具概览

206 个工具：178 个只读 · 28 个写入 · 5 个破坏性工具——直接从注册表统计，而非手动计算。docs/tool-manifest.json 由实时 FastMCP 注册表生成（make tool-manifest），CI 门禁会在文件与代码不一致时阻止构建。每个工具的描述、安全注释和参数都在其中；包含切片跟踪的说明性目录位于 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 · 预配 · 设置与功能 · 告警与通知器。

默认情况下，全部 206 个工具都会公开——每个工具的架构都由 Claude Code 自身的搜索功能延迟加载，因此缩小默认工具集只会让其他宿主受益，却牺牲了优秀宿主的体验。受限的宿主（例如小型本地模型、上下文预算紧张的宿主）可以通过 RANCHER_TOOLSETS 选择较小的工具集；请参阅配置中的工具集配置。

快速开始

要求

• Python 3.12+ 和 uv
• Rancher API 令牌（创建令牌）

安装与运行

# From source
git clone https://github.com/rex/mcp-rancher.git
cd mcp-rancher
make setup                 # deps, .env scaffold, pre-commit hooks
cp .env.example .env       # set RANCHER_URL + RANCHER_TOKEN
make dev                   # run the MCP server (stdio)

发布到 PyPI 后，只需一行：uvx rancher-mcp。

Claude Code

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 Desktop

{
  "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"
      }
    }
  }
}

多个实例

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 的实例会拒绝所有变更操作。

架构

flowchart LR
    A[MCP client<br/>Claude Code · Claude Desktop · any] -- stdio --> S

    subgraph S[rancher-mcp]
        direction TB
        L1[Discovery & schema<br/>planes · schemas · capabilities]
        L2[Generic engine<br/>any resource · both planes<br/>CRUD · actions · links · watch]
        L3[Curated tools<br/>typed models · shaped output<br/>next-step hints]
        G[Safety layer<br/>read-only guard · confirmation phrases<br/>audit log · rate limit · masking]
        L1 --> L2 --> L3
        L3 --> G
        L2 --> G
    end

    G -- Norman /v3 --> R1[(Rancher<br/>instance A)]
    G -- Steve /v1 + k8s proxy --> R1
    G -- Norman + Steve --> R2[(Rancher<br/>instance B)]

架构分为三层，彼此有意分离：发现用于了解实例能做什么，通用引擎可以操作实例公开的任何资源，而精选工具则让常见操作路径具备类型化、结构化且自描述的特性（每个响应都包含 suggested_next_steps）。大多数精选工具都根据 YAML 描述符生成（catalog/curated_tools/），并设有防漂移门禁——编辑决策由描述符承载，而非样板代码。

安全模型

专为 Agent 连接到关系到你薪水的集群而设计：

防护措施	行为
只读实例	read_only: true 会在工具逻辑运行前，拒绝对该实例的所有修改操作
破坏性操作确认	删除操作必须输入明确的确认短语（例如 "delete steve namespace foo"）——未提供短语就不能删除
工具注解	每个工具都会声明 readOnlyHint / destructiveHint / idempotentHint，客户端可以据此控制用户体验
审计日志	每次修改操作都会生成结构化的 event="audit" 记录，包含工具、操作、平面、实例、资源和结果。仅记录参数名称，绝不记录参数值
速率限制	对写入操作实施令牌桶限流（默认每分钟 60 次）——失控的循环无法对你的 API 进行连发调用
密钥与私钥屏蔽	精选响应中不会包含密钥值和证书私钥（只有显式选择通用工具才会显示）
结构化错误	防护机制拒绝请求时会返回带类型的 error_code 错误封装，Agent 可以据此分支处理——绝不返回原始字符串

兼容性

主要目标版本	Rancher 2.9.3（已通过生产环境验证）
兼容性下限	Rancher 2.6.5（通过能力检测保持兼容）
API 平面	Norman /v3 + Steve /v1（以及按集群划分的 Kubernetes 代理）
传输方式	stdio

能力检测会在运行时弥合版本差异——无需固定版本构建，也不会出现“只在我的 Rancher 上可用”的情况。两个目标版本都通过同一套测试套件进行验证，且已在 2.6.5 实验环境和 2.9.3 生产集群上对读取路径进行了实时验证 （验证报告）。

配置

变量	默认值	用途
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 表示禁用）
RANCHER_TOOLSETS	all	启动时公开的工具集配置（可用逗号分隔多个）——见下文
RANCHER_TOOLS	—	在所选配置之外，强制包含的工具名称（以逗号分隔）
RANCHER_EXCLUDE_TOOLS	—	要移除的工具名称（以逗号分隔，最后应用）——始终优先于 RANCHER_TOOLS

工具集配置文件

默认值为 all：所有工具都会保持启用。主机 Claude Code 会将每个工具的架构都置于自己的搜索功能之后，因此，较小的默认配置只会让其他主机受益，却会让这款优秀的主机体验变差——这是有意为之，并非疏忽。

RANCHER_TOOLSETS 可让受限主机（例如小型本地模型或上下文预算有限的主机）使用更小的工具集。值可以是某个系列名称——对应 src/rancher_mcp/tools/ 中的一个模块（storage、workloads、pods_services、rbac 等；完整列表请参阅 rancher_mcp.toolsets.FAMILY_REGISTRARS）——也可以是跨系列的 core 配置文件：一组约 32 个用于分类处置和掌握概况的工具（rancher_find_*、健康状态／摘要汇总、核心列表／获取工具对，以及通用的 rancher_{steve,norman}_resource_{list,get} 备用入口）。core 会将 tools/list 载荷从 206 个工具／约 401 KB 缩减为 32 个工具／约 78 KB（缩小约 80%）。配置文件可以组合：RANCHER_TOOLSETS=core,storage 表示启用分类处置工具集以及所有与存储相关的工具。

RANCHER_TOOLSETS=core                        # small triage surface
RANCHER_TOOLSETS=core,storage,workloads      # triage + two full families
RANCHER_TOOLS=rancher_secret_get             # add one extra tool on top
RANCHER_EXCLUDE_TOOLS=rancher_secret_create  # remove one, wins over the above

如果配置文件名称未知，启动时会明确报错，而不会静默地产生空工具集或缩小后的工具集。调用一个实际存在但未包含在当前配置文件中的工具时，会返回结构化的 TOOLSET_NOT_ENABLED 错误，指出工具名称、启用该工具所需的工具集，以及需要设置的环境变量——绝不会只返回“未知工具”，以免无法区分工具已停用和名称拼写错误。

项目状态

已发布，且在读取、分类处置和受控写入操作方面稳定。对于其他方面，现状如下：

• 破坏性工作流（节点排空、etcd／备份恢复、证书轮换、集群升级／删除）仍在路线图中——有意安排在经过真实环境中的读取路径验证之后。通用引擎和确认保护机制已可供今天就需要这些操作的运维人员使用。
• Alertmanager 路由／静默功能需要集群内 API 集成，因此暂缓实现。
• 完整的逐版本兼容性矩阵（Track G）正在编制中；首次实时验证运行涵盖了两个目标环境的读取矩阵。

工作按工具进行跟踪：docs/tool-catalog.md（每个工具都有一行记录，每个缺口都有一个切片 ID）以及 ROADMAP.md。

开发

make help               # every target, documented
make validate           # codegen drift + manifest drift + architecture + lint + typecheck + tests
make tool-manifest      # regenerate docs/tool-manifest.json from the registry
make lab-up             # local Rancher 2.6.5 lab (kind + helm), fully scripted
make integration-current # isolated Rancher 2.14.3 end-to-end test run
make live-read-matrix   # read-only validation probes against configured instances
make mock-rancher       # fixture-backed mock Rancher for provider-config testing

• 本地实验环境 — 在 kind 上运行的独立 Rancher 2.6.5，带有模拟的下游集群；使用仓库本地的 kubeconfig，绝不触碰你机器上的状态。
• 当前集成实验环境 — 在独立的 Kind 集群上运行 Rancher 2.14.3，使用端口 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 · httpx · Pydantic v2 · structlog · uv

安全

有关威胁模型、令牌使用指南和漏洞报告方式，请参阅 SECURITY.md。

许可证

MIT