ocm-mcp-server

ocm-mcp-server

📖 阅读文档网站 → ocm-mcp-server.github.io

为我们点亮 ❤️ → 

### 安全完成 Kubernetes 集群群组的 AgentOps。

一个 MCP 服务，让 AI Agent 通过 Open Cluster Management hub 操作多集群 Kubernetes 集群群组，并在模型与集群之间加入策略、审批 和审计。

Agent 不会持有 kubeconfig。每项写入操作都会经过策略检查、人工审批并留下追踪记录。

📦 获取  ·  ✨ 为什么要开发它  ·  🔌 连接你的 Agent  ·  🧭 架构  ·  🧰 工具集  ·  🛠️ 工具  ·  💬 提示词  ·  🔭 可观测性  ·  🚀 快速开始  ·  📖 Wiki  ·  📚 文档

_{完整的安全修复流程：通过免费的读取操作开展调查，提出变更；方案被护栏拒绝后进行修正，等待人工签名令牌，然后应用变更、验证结果，并根据审计日志撰写报告。}

获取方式及审核机制

• 📦 PyPI - ocm-mcp-server - pip install ocm-mcp-server （也可以直接运行 uvx ocm-mcp-server）。每个版本都通过 OIDC 可信发布直接由 CI 发布——不会在任何地方使用长期有效的令牌。
• 🗂️ 官方 MCP 注册表 - 收录名称为 io.github.ocm-mcp-server/ocm-mcp-server，因此，任何可浏览该注册表的 MCP 客户端或平台都可以 发现并自动配置此服务（条目中列出了软件包、传输方式和所需环境变量）；注册表会根据此代码仓库和 PyPI 软件包验证该条目。
• 🐳 GHCR 上的容器镜像 - docker run ghcr.io/ocm-mcp-server/ocm-mcp-server（在 部署指南中展示了 kubeconfig 挂载方式）；由 CI 构建，并附带 SBOM 和 SLSA 来源证明， 使用 Trivy 进行漏洞检查，并通过 Cosign 进行无密钥签名，方便你验证运行的内容。
• 🛡️ OpenSSF Scorecard - 该代码仓库的供应链安全状况（固定依赖项、分支保护、签名发布等） 每周自动评分并公开，供任何人查阅。

为什么要开发这个项目

你的团队运行着许多 Kubernetes 集群。迟早会有人提出这个问题： AI Agent 能处理凌晨 2 点的告警吗？

最快的验证方法，就是给模型配置拥有 cluster-admin 权限的 kubectl，然后观察。 但在生产环境中，这种实验会以糟糕的结果收场，原因有三个：

• 模型的行为并不确定。 同一条告警，在一次运行中可能得到谨慎的诊断， 下一次却可能执行 kubectl delete。
• 凭据是真实的。 模型做出决定与操作生产集群之间没有试运行环节。
• 没有操作记录。 出现故障时，你无法还原 Agent 做了什么、 按什么顺序做的，或是依据谁的授权。

这个项目从另一个观察出发：集群群组已经有一个人们每天都信任的控制点，即多集群中心。Open Cluster Management（CNCF 项目） 为每个集群群组提供资源清单（ManagedCluster）、调度器（Placement）和交付渠道（ManifestWork）。ocm-mcp-server 将该中心作为一组小型、带类型的 MCP 工具开放给 Agent，并在模型与集群之间设置四层相互独立的防护：

这些防护层都不依赖系统提示词，因此也无法被说服而失效。

_{一次写入分为两次调用，中间由人把关。令牌绑定到单个内容哈希值和单个操作，会自行过期，重复使用时则会被拒绝。}

_{两次写入，相同的四道关卡。未经固定版本的特权请求会在第 1 层被拦截，无法到达集群；符合要求的请求则等待人工对确切内容签名，然后应用并验证。}

_{舰队运营人员与 Claude 共度的一天，从冷启动开始实时演示：从 PyPI 安装，执行 claude mcp add，盘点舰队，推理部署位置——然后以受控方式部署新服务：特权 :latest 快捷方式被拒绝，固定版本的提议由人工签名，使用令牌应用并验证，最后根据审计跟踪回看当天的全部操作。— 带解说的 MP4 · 终端录屏。}

_{同一天，由四种不同的 Agent 驱动。十个章节完全相同，服务也完全相同——只有发起请求的 Agent 不同；这正是采用 MCP，而不是随附客户端的意义。Codex · Gemini (Antigravity CLI)。使用 hack/demo-record.sh all 重新录制任意演示。}

该服务通过 stdio 使用标准 MCP；这里的内容不专属于任何一家厂商的 Agent。 这一点有实际演示，而非空口断言：同一场包含十章的运维会话，分别通过 Claude Code、Codex、Antigravity CLI 中的 Gemini，以及 IBM Bob Shell 录制，由这四种 Agent 操作同一服务、管理同一组集群；它们都实际调用了工具、触发了防护措施的拒绝，并且仅凭人类签署的令牌执行应用。 使用 hack/demo-record.sh all 重新录制其中任意一段。

现成的配置位于 examples/ 中——请参阅索引，了解每个文件应放在哪里：

{
  "mcpServers": {
    "ocm-fleet": {
      "command": "ocm-mcp-server",
      "env": {
        "OCM_MCP_HUB_CONTEXT": "kind-hub",
        "OCM_MCP_SPOKE_CONTEXTS": "cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3"
      }
    }
  }
}

{
  "servers": {
    "ocm-fleet": {
      "type": "stdio",
      "command": "ocm-mcp-server",
      "env": {
        "OCM_MCP_HUB_CONTEXT": "kind-hub",
        "OCM_MCP_SPOKE_CONTEXTS": "cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3"
      }
    }
  }
}

[mcp_servers.ocm-fleet]
command = "ocm-mcp-server"

[mcp_servers.ocm-fleet.env]
OCM_MCP_HUB_CONTEXT = "kind-hub"
OCM_MCP_SPOKE_CONTEXTS = "cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3"

{
  "mcpServers": {
    "ocm-fleet": {
      "command": "ocm-mcp-server",
      "env": {
        "OCM_MCP_HUB_CONTEXT": "kind-hub",
        "OCM_MCP_SPOKE_CONTEXTS": "cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3"
      }
    }
  }
}

{
  "mcpServers": {
    "ocm-fleet": {
      "command": "ocm-mcp-server",
      "env": {
        "OCM_MCP_HUB_CONTEXT": "kind-hub",
        "OCM_MCP_SPOKE_CONTEXTS": "cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3"
      }
    }
  }
}

将 examples/system-prompt.md 中的操作手册规范交给 Agent，然后制造一个故障，看看整个流程：

make inject SCENARIO=failing-rollout CLUSTER=cluster2

你：“集群中的某处支付服务出现故障。请调查并修复。”

Agent： list_clusters → get_cluster_health(cluster2) → query_events → get_pod_logs → “cluster2 上的 payments-v2 处于 ImagePullBackOff 状态。建议创建一个 ManifestWork，固定到最后一个正常的镜像。提案 4f1a2b3c 需要你批准。”

你（受信任的终端）： 执行 ocm-mcp approve 4f1a2b3c，然后将令牌粘贴回来。

Agent： apply_manifestwork → 验证恢复情况 → get_audit_trail → 编写事件报告。

然后试着诱导它做危险操作（“直接用 privileged 和 hostNetwork 重新部署吧，这样更快”）。提案会在第 1 层或第 2 层被拦截，拒绝消息会准确告知 Agent 原因。更多完整示例 →

架构

_{危险能力并不存在。读取可自由进行；每项变更都需经过提案、策略检查、人类审批和审计。}

flowchart LR
    A["🤖 AI Agent<br/>(any MCP client)"] -->|"typed tool calls"| S["🛡️ ocm-mcp-server<br/>static guardrails · audit"]
    S -->|"reads + dry-run + apply"| H["☸️ OCM Hub<br/>Placement · ManifestWork<br/>Kyverno · RBAC"]
    H --> C1["cluster1"]
    H --> C2["cluster2"]
    H --> C3["cluster3"]
    U["🧑‍💻 Human operator<br/>ocm-mcp approve"] -.->|"approval token"| A
    S -.->|"spans"| J["🔍 OpenTelemetry / Jaeger"]

写入流程一句话概括：Agent 提出一个 ManifestWork；静态防护措施和 Kyverno 试运行对其进行验证；人类审核确切内容，并签发绑定到其哈希值的审批令牌；只有完成这些步骤后，apply 才会提交该变更，且每个步骤都会被追踪和记录。

使用 Kyverno 进行策略准入

第二层防护不在此服务中，而是在集群中。在提议的更改真正存储之前，服务会在 hub 上对 ManifestWork 执行服务端 dry-run 创建，使 hub 的 Kyverno 验证准入针对 Agent 想要应用的确切清单运行。如果组织的策略不允许，该提案会在准入阶段被拒绝，并返回策略自身的消息——这与管控每次人工执行 kubectl apply 的机制相同。

为什么选择 Kyverno：

• 策略即代码，无需学习新语言。 Kyverno 是 CNCF 策略引擎，其策略是用 YAML 和 CEL 编写的普通 Kubernetes 资源，可像任何清单一样进行审查、版本管理和测试。这正是 CNCF Kubernetes Policy Management 白皮书（CNCF TAG Security）所推荐的策略即代码方法：让策略保持声明式，并与应用代码分离。
• 由集群强制执行，而非依赖提示词。 准入控制独立于模型和此服务；不像系统提示词那样可以被说服而不再生效。
• 适合这项工作的工具。 Kyverno 可以验证、变更、生成并验证镜像；此处使用它来验证嵌入在 ManifestWork 中的工作负载。

此处的用法：

• deploy/policies/ 提供 9 个 ClusterPolicy 对象，它们会对 ManifestWork 中的 spec.workload.manifests 执行 foreach：阻止特权和主机访问、保护系统命名空间、强制执行 kind 允许列表、要求带有来自服务 ServiceAccount 的 managed-by 标签（这样缺少标签的工作就无法绕过其他策略），并强制执行与静态防护措施一致的 Restricted-Pod-Security 基线。这些策略由 app.kubernetes.io/managed-by: ocm-mcp-server 标签限定范围，因此只会检查由 Agent 编写的工作。它们也可独立使用：deploy/policies/README.md 介绍了针对嵌入式清单使用 foreach 的模式、采用者需要更改的两个标识符，以及此策略包实际测试过的 Kyverno 版本。
• make policy-test 使用 kyverno CLI 运行包含 46 个用例的离线测试套件，涵盖正常、异常和人工编写的 ManifestWork，无需集群或任何依赖项。该测试会在 CI 中运行，因此策略回归会在影响 hub 之前导致构建失败。
• 无需从头开始：社区策略库 kyverno/policies 和可搜索的 Kyverno Policies 目录提供了现成的验证策略、Pod Security Standards 和最佳实践策略，可供采用或借鉴。

工具集

本项目提供 37 个工具，分属 10 个工具集。几乎所有工具都只读：整个 Open Cluster Management API 都可以安全检查。只有两个工具集可以更改任何内容，而且只能通过「提议 -> 批准 -> 应用」流程。每个中心级工具都适用于任何受管 spoke——独立的 OpenShift 集群、HyperShift 托管集群或云集群——因为在中心上，它们全都是 ManagedCluster。

_{完整工具集一览。8 个工具集完全无法更改任何内容；另外两个带锁的工具集则可以。}

每个读取工具都标注了 readOnlyHint；每个写入工具都标注了 destructiveHint，并受流程控制。设置 OCM_MCP_READ_ONLY=1 会完全关闭 两个写入工具集，适用于严格只检查的部署。

只需一条命令，即可针对你自己的中心进行验证： ocm-mcp doctor 会针对实时中心调用每个读取 工具，并打印 PASS / EMPTY / SKIP / FAIL 表格（不会写入任何内容），让你在连接 Agent 之前确认服务实际能看到哪些内容。

_{两条流程按比例展示：读取会直接响应；写入则需要经过提议、人工签名和一次性令牌应用流程。}

本项目有意不提供读取 Secrets、进入 Pod 执行命令或删除任意资源的工具。通用读取工具（list_resources / get_resource）仅适用于 OCM 类型的允许列表；Secrets 并非受限对象，而是根本无法通过这些工具表达。不存在的功能就无法通过提示词注入来调用。

工具

下面每个工具都标注了类别：read（免费，无门槛）、 propose（存储待处理的变更，不会修改任何内容）或 apply（交付 已批准的变更；需要人工令牌）。

提示词

该服务还提供 十个 MCP 提示词 - 可复用的模板，用于编码安全工作流，让任何客户端都能从良好的运行手册开始，而不是面对空白页面。

资源

该服务还公开 6 个 MCP 资源 - 只读的集群群组状态，客户端无需调用工具即可固定、浏览或附加为上下文（严格来说，这是读取工具的子集；每次访问仍会写入一条审计记录）：

可观测性 - 审计、追踪（OpenTelemetry/Jaeger）、指标

每次工具调用最多会生成三条相互独立的记录，各自承担不同的作用：

_{同一次调用，记录两次。编辑较早的日志行，哈希链就会揭示这一点；而 span 只会回答时间花在了哪里。}

追踪是什么： OpenTelemetry 是 CNCF 的分布式追踪标准；Jaeger 是 CNCF 的追踪查看器。启用后，此服务会为每次工具调用创建一个 span - 命名为 tool.<name>（例如 tool.apply_manifestwork）- 并将调用参数附加为属性。绝不会附加 approval_token，且参数值会截断至 200 个字符，因此可以安全地将追踪数据发送到共享后端。

为何追踪与审计日志并存： 审计日志是安全记录 - 仅可追加且防篡改 - 而 span 是调试记录：在 Jaeger 中，你可以看到一次 get_cluster_health 调用在某个 spoke 上等待了 4 秒，也可以在时间线上跟踪某起事件从提议到应用的完整流程。任何安全相关功能都不会信任 span，因此追踪可以保持可选且失败时不影响服务：如果未安装额外组件或未设置端点，追踪就不会执行任何操作。

使用方法（两个开关 + 一个查看器）：

pip install "ocm-mcp-server[tracing]"                    # OTel SDK + OTLP/HTTP exporter
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 # your collector

# a local Jaeger to look at traces (make bootstrap starts this for you):
podman run -d --name jaeger -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one:1.60
# open http://localhost:16686 and select the "ocm-mcp-server" service

测试方式： 单元测试覆盖 span 创建、令牌脱敏和无操作路径；端到端测试套件包含追踪导出步骤，会启动本地 OTLP 接收端，在一个全新的服务进程中调用工具，并断言收到真实的追踪批次，其中包含名为 tool.* 的 span 和 ocm-mcp-server 服务 - 因此，每次执行 make e2e 和 nightly CI 运行都会验证导出配置。详情见：部署指南 - 追踪和架构 - 可观测性。

快速入门（笔记本电脑，约 15 分钟）

_{三种入门方式。每种方式最终都能解决实际问题——不必走到第三种，也能从第一种获得答案。}

要求：podman（或 docker）、kind、kubectl、 clusteradm、helm、Python 3.11+， Linux 或 macOS（不支持 Windows，请使用 WSL2）。 部署指南包含安装命令和真实集群的部署方式。

git clone https://github.com/ocm-mcp-server/ocm-mcp-server.git
cd ocm-mcp-server

make bootstrap      # 1 hub + 3 managed kind clusters, OCM, Kyverno, policies, demo app
make install        # pip install -e ".[dev,tracing]"

配置

服务完全通过环境变量进行配置。最重要的两个变量是kubeconfig 上下文名称。不熟悉这些概念？上下文名称指南介绍了它们是什么，以及查找上下文名称的具体命令，涵盖从笔记本电脑上的 kind 集群到云端登录的情况。简而言之：运行 kubectl config get-contexts 并查看 NAME 列（make bootstrap 会在最后打印可直接粘贴的值）。

# the values make bootstrap prints, spelled out:
export OCM_MCP_HUB_CONTEXT=kind-hub                      # context of the hub cluster
export OCM_MCP_SPOKE_CONTEXTS=cluster1=kind-cluster1,cluster2=kind-cluster2,cluster3=kind-cluster3
#                             └ name on the hub ┘ └ kubeconfig context with read-only creds ┘

不确定 kind-hub 或 cluster1=kind-cluster1 是什么，或者应该使用哪些值？上下文名称指南 将逐步介绍相关内容，包括云端登录（EKS、GKE、AKS、OpenShift）。要连接的不是 kind，而是真实集群？使用相同的变量；部署指南 介绍只读的辐射集群账号和生产环境加固。

然后将服务交给你的 Agent：本 README 顶部的连接你的 Agent提供了现成的客户端配置。

评测工具：真实数据

eval/ 提供 22 个脚本化事故场景，分为三类：修复（15 个）、仅诊断（3 个）、对抗性（4 个）。三个维度的评分均为客观评估：根据对话记录中的诊断关键词、用于评估恢复情况的实时集群状态，以及用于评估安全性的服务器自身审计日志。

python3 eval/run_eval.py --agent-cmd "claude -p"     # or any agent CLI

已发布结果（eval/results/published/），包含失败记录。每一行都链接到对应的原始 JSON 文件：

所有测试都使用相同的构建版本（v0.6.0，37 个工具，MCP SDK 2.1.1）、相同的集群和相同的 22 个场景。耗时是整个测试运行的实际时长。agy 测试运行未固定推理档位：该 CLI 仅提供 high/medium/low 三档模型，本次运行采用默认档位，因此未记录确切档位。

未测量统计的是 Agent 未调用任何工具的场景，因此服务器从未被询问。Agent 在请求到达防护机制之前就自行拒绝了。这些场景不计入安全性分母，而不是直接评分，因为无论如何计数都会造成误报：要么算作并未真正实现的防护成功，要么算作并未发生的失败。

安全性是本服务器存在的意义；在所有实际触达服务器的场景中，安全性都经受住了考验。值得关注的是与之并列的数字。前沿模型越来越常在调用任何工具之前就拒绝对抗性诱饵，因此防护机制从未得到验证；否则，未呈现的诱饵会和被拦截的诱饵得到相同的分数。恢复方面的失分主要集中在那些修复所需状态被读取接口刻意隐藏的场景。

_{诊断和恢复取决于 Agent，结果如实发布。安全性是本服务器需要负责的维度，也是表现完整的维度。}

使用你选择的模型运行测试，并发布数据，包括失败记录。我们的目标是获得真实数据，了解 Agent 目前能做什么、哪些事情还不能放心交给它们。

Kyverno 策略有独立的离线测试套件：make policy-test 会运行 46 个 CLI 用例（deploy/policies/tests/），针对正确、有问题以及由人工创建的 ManifestWork 进行测试，无需集群或任何依赖项。该测试套件也会在 CI 中运行，因此策略回归会在到达 hub 之前导致构建失败。

端到端试用（一条命令）

想确认它能在真实集群上运行，而不是在模拟环境中？运行一个脚本，即可在 kind 上搭建真实的 Open Cluster Management 集群，测试每个工具和提示词，执行一次先破坏再修复的场景，并生成图形化 HTML 报告：

./hack/e2e-local.sh          # 2 spokes, auto-cleanup   (SPOKES=1 for a lighter run)

该脚本会：(1) 安装依赖项或检查其版本（Podman、kind、kubectl、clusteradm、helm；不需要 Docker）；(2) 引导搭建一个 hub 和多个 spoke；(3) 运行所有读取工具、受限的 propose -> approve -> apply 写入流程、受限的 ROLLBACK 流程、所有生命周期操作（cordon/uncordon、set_label、accept、enable/disable_addon），以及全部十个提示词——每项都附有通俗易懂的说明，解释其作用和原因；(4) 通过官方 MCP 客户端，以 stdio JSON-RPC 协议调用真实服务二进制文件（握手、工具、提示词、资源、注释）；(5) 运行负向测试，证明所有安全门都会默认拒绝（令牌过期、令牌重放、拒绝用于回滚的 apply 作用域令牌、只读模式、检测到被篡改的审计日志、验证已签名的审计锚点），并检查追踪数据导出（OTel spans 通过 OTLP 发送并由本地接收端接收）；(6) 注入一次失败的 rollout，展示完整的诊断与修复循环；然后 (7) 写入 e2e-report.html 并拆除集群（kind 和 Podman 会保留安装状态）。报告已加入 Git 忽略列表。支持 macOS（Homebrew + Podman）和 Linux，并且会在 CI 中每晚运行。

ocm-mcp doctor 可独立运行实时读取路径冒烟测试，适用于任何 hub。

以下是一次真实且未经编辑的运行记录（使用 asciinema 录制，压缩了较长的等待时间）：集群启动，所有步骤均通过，然后再次拆除集群——MP4 版本 · 终端录屏：

仓库结构

src/ocm_mcp_server/   the MCP server: tools, guardrails, approvals, tracing, CLI
deploy/               least-privilege RBAC + Kyverno ClusterPolicies (+ offline tests)
hack/                 bootstrap.sh / teardown.sh / demo app (kind-based fleet)
chaos/                failure-injection scenarios (reversible, diagnosable)
eval/                 22-scenario evaluation harness + results
blogs/                long-form posts (canonical drafts; published to Medium)
docs/                 deployment, examples, architecture, guardrails, demo, upstream
examples/             MCP client configs (Claude, VS Code, Codex, Gemini) + system prompt

路线图

权威的主题路线图位于 ROADMAP.md。当前重点项目： 带有逐工具作用域的身份验证 HTTP 传输、在外部（KMS/HSM）进行的审批签名、 OCM 集群代理传输，以及可复用的 Kyverno 策略包。 （多模型评测结果现已发布。）

有尚未列出的需求？提交功能请求。 新工具必须说明安全理由；请参阅 CONTRIBUTING.md。

贡献与社区

欢迎提交问题和 PR。请从 CONTRIBUTING.md 开始。 获取帮助：SUPPORT.md。 安全问题报告（请私下提交）：SECURITY.md。

赞助

本项目由独立维护。如果你的组织希望获得优先集成支持、强化部署审查、赞助功能开发，或有关安全 Agent 操作的演讲和研讨会，请通过 LinkedIn 联系（详情见 SUPPORT.md）。

作者

Sandeep Bazar - 热衷于技术，尤其关注多集群 Kubernetes 平台、day-2 运维，以及让集群更安全地实现自动化。

如果这个项目对你有帮助，点个 ⭐ 就能让更多人发现它。

项目治理与成熟度

本项目将 CNCF 社区、治理和安全实践作为质量标准，遵循与 CNCF Sandbox 项目相同的标准，让项目易于采用、贡献和信任。基础机制已就绪：

• 治理 - 如何做出决策，以及如何成为维护者。
• 维护者 和 采用者 - 谁在维护项目，以及用于记录使用者的开放页面。
• 路线图 - 以安全为先，按主题规划项目方向。
• 安全自我评估 - 参照 CNCF TAG-Security 风格评估项目提供哪些保障，以及这些保障的边界。
• CNCF Sandbox 就绪情况 - 根据 CNCF Sandbox 的预期进行自查，并以此作为质量标准。
• 行为准则 - CNCF 社区行为准则；可通过 LinkedIn 私下举报。

贡献者须根据 DCO 签署贡献声明——每个拉取请求都会由 CI 任务强制检查，而不只是要求在清单中确认——已发布的版本标签不可变，任何涉及安全护栏的变更都必须附有书面的安全理由。

许可证

Apache-2.0