mcp-kubernetes

mcp-kubernetes

一个面向 Kubernetes 的模型上下文协议服务。它允许支持 MCP 的客户端（Claude Desktop、Claude Code 等）检查和操作多个上下文中的 Kubernetes 集群——行为完全由标志控制。

设计目标是默认安全：服务以只读模式启动，可限定为允许列表中的命名空间和上下文，保护系统命名空间免受修改，并要求显式启用才能执行危险操作（删除、应用、执行）。

功能

• 多集群 — 每个工具都接受可选的 context；可通过允许列表限定可用的上下文。
• 访问模式 — read-only → read-write → admin，逐层递增，确保某个模式不会开放超出其级别的工具。
• 安全标志 — 命名空间允许列表、受保护的命名空间、上下文允许列表，以及针对删除 / 应用 / 执行的独立启用选项、试运行和 JSON 审计日志（见下文）。
• 标准身份验证 — 使用你的 kube-config（或集群内服务账号）。服务不会存储任何凭据。

安全模型

关注事项	标志	默认值	效果
服务总体上可以执行哪些操作？	K8S_MODE	read-only	read-only 仅开放读取操作；read-write 增加修改操作；admin 增加破坏性工具。高于当前模式的工具绝不会注册。
哪些命名空间在作用范围内？	K8S_NAMESPACE_ALLOWLIST	(全部)	设置后，任何针对列表之外命名空间的操作都会被拒绝。
哪些命名空间始终为只读？	K8S_PROTECTED_NAMESPACES	kube-system,kube-public,kube-node-lease	可以读取，但无论模式如何，都不能修改或删除。
可以访问哪些集群？	K8S_CONTEXT_ALLOWLIST	(全部)	设置后，只能将这些 kube-config 上下文作为目标。
是否可以删除？	K8S_ALLOW_DELETE	false	delete_resource 需要启用此选项，且处于 admin 模式。
是否可以应用清单？	K8S_ALLOW_APPLY	false	apply_manifest 需要启用此选项，且处于 read-write 模式。
是否可以在 Pod 中执行命令？	K8S_ALLOW_EXEC	false	exec_in_pod 需要启用此选项，且处于 admin 模式；否则甚至不会注册该工具。
预览操作而不触及集群	K8S_DRY_RUN	false	写入 / 管理工具会先验证并记录操作意图，然后直接返回，不会调用 API。
审计跟踪	K8S_AUDIT_LOG	true	每次受保护的操作都会向 stderr 输出一行 JSON（ALLOW / DENY / DRY_RUN）。
交互式确认	(自动)	—	运行破坏性和高影响操作前，会通过 MCP 引导机制提示用户批准；不支持引导机制的客户端则会回退到 *_ALLOW_* 门控。

这些层彼此独立——例如，admin 模式下若三个启用选项均为 false，仍可重启和扩缩部署，但不能删除资源，也不能在 Pod 中执行命令。

工具

读取（read-only+）：list_contexts、list_namespaces、list_pods、get_pod、get_pod_logs、list_deployments、list_services、list_nodes、list_events、get_resource

写入（read-write+）：scale_deployment、restart_deployment、set_deployment_image、create_namespace、apply_manifest（需要 K8S_ALLOW_APPLY）

管理（admin）：delete_resource（需要 K8S_ALLOW_DELETE）、exec_in_pod（需要 K8S_ALLOW_EXEC）

可选的 AI 风险防护。 设置 K8S_GUARD_MODE=monitor|enforce，让 delete_resource、exec_in_pod 和 apply_manifest 在运行前调用本地 laya-guard 守护进程（pipx install laya-guard && laya-guard），对操作进行分类，判定为允许／确认／阻止。该防护在删除／执行／应用权限门控之后运行；只会收紧限制，绝不会授予权限；出错时默认拒绝。

快速开始 — 添加到你的 Agent

已在 npm 上发布为 @dockndevai/mcp-kubernetes。无需克隆或构建 — 你的 MCP 客户端会按需通过 npx 运行。请从 read-only 模式开始；所有变量请参阅 .env.example，完整的客户端指南请参阅 docs/CLIENTS.md。

Claude Code（命令行）

claude mcp add kubernetes -e KUBECONFIG_PATH="/Users/you/.kube/config" -e K8S_MODE="read-only" -- npx -y @dockndevai/mcp-kubernetes

Claude Desktop · Cursor · Windsurf — 在 claude_desktop_config.json、.cursor/mcp.json 或 ~/.codeium/windsurf/mcp_config.json 中使用相同配置：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kubernetes"
      ],
      "env": {
        "KUBECONFIG_PATH": "/Users/you/.kube/config",
        "K8S_MODE": "read-only"
      }
    }
  }
}

OpenAI Codex CLI — 在 ~/.codex/config.toml 中：

[mcp_servers.kubernetes]
command = "npx"
args = ["-y", "@dockndevai/mcp-kubernetes"]
env = { KUBECONFIG_PATH = "/Users/you/.kube/config", K8S_MODE = "read-only" }

VS Code（GitHub Copilot，Agent 模式） — 在 .vscode/mcp.json 中：

{
  "servers": {
    "kubernetes": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@dockndevai/mcp-kubernetes"
      ],
      "env": {
        "KUBECONFIG_PATH": "/Users/you/.kube/config",
        "K8S_MODE": "read-only"
      }
    }
  }
}

从源代码运行（开发）

建议使用上文发布的包。若要从克隆的仓库运行：

npm install
npm run build
node dist/index.js   # with the environment variables set

开发

npm run dev        # watch mode
npm test           # unit tests for the security policy
npm run typecheck

发布

此服务包含供官方 MCP 注册表使用的 server.json，以及用于 npm 所有权验证的 mcpName。有关发布到 npm 并在 MCP 注册表、Smithery、Glama、Cursor 和 PulseMCP 上列出的说明，请参阅 PUBLISHING.md。

许可证

MIT