Kubernetes Read Only MCP Server

mcp-k8s-ro

一款只读 MCP 服务，可让 Claude 访问 Kubernetes 集群。使用 Go 构建，通过 stdio 使用 MCP 协议进行通信。

设计

• 只读 — 仅支持 get、describe、logs 和 top 等操作。不支持创建、更新或删除。如果需要执行变更操作，服务会输出对应的 kubectl 命令，供你手动运行。适合夜间值班时安全使用：即使提示词疲劳，Claude 也绝不会意外修改你的集群。
• 安全处理 Secret — 在将 Secret 值发送给模型前会对其进行掩码处理，避免因配置错误或提示词注入导致 Secret 泄露。
• 节省 Token — 响应只包含相关字段（名称、状态、重启次数等），而非原始 Kubernetes API 对象，从而减少上下文用量。
• 感知集群信息 — 每条响应都包含当前上下文和集群名称，因此 Claude 始终知道自己正在与哪个集群交互。
• 固定上下文 — 服务启动时会锁定当前活动的 kubeconfig 上下文。在另一个终端切换上下文不会影响正在运行的服务。
• 无需额外基础设施 — 可作为本地二进制文件或 Docker 容器运行，并连接到启动时处于活动状态的 kubeconfig 上下文。

已脱敏字段

对象/字段	原因
Secret.data	防止 Secret 泄露
Secret.stringData	防止 Secret 泄露
CertificateSigningRequest.spec.request	大型 base64 PEM 数据块，没有诊断价值，可节省 Token
Certificate (cert-manager) .spec.keystores	证书链 PEM 数据块，没有诊断价值，可节省 Token
Certificate (cert-manager) status.conditions[].message	证书链 PEM 数据块，没有诊断价值，可节省 Token
*.managedFields	没有诊断价值，可节省 Token

工具

工具	描述
k8s_list_resources	按名称列出任意资源类型，例如 Pod、Deployment、CRD 等。可选择按命名空间筛选。根据资源类型返回名称、状态、就绪情况、重启次数、节点、IP 等信息。
k8s_describe_resource	返回单个资源的完整 YAML。Secret 数据会被屏蔽。
k8s_list_resource_types	通过发现 API 列出所有可用资源类型。可选择按 API 组筛选。
k8s_get_logs	获取 Pod 日志。支持容器选择器、尾部行数，以及用于崩溃容器的 --previous。
k8s_get_events	列出某个命名空间或整个集群的 Kubernetes 事件，并按最近时间排序。
k8s_top_pods	显示每个 Pod 的 CPU 和内存使用情况，并按容器细分。需要 metrics-server。
k8s_top_nodes	显示每个节点的 CPU 和内存使用情况，以及占可分配容量的百分比。需要 metrics-server。

配置

环境变量	默认值	描述
KUBECONFIG	~/.kube/config	kubeconfig 文件路径

在 Claude 中使用

Docker（推荐）

claude mcp add --scope user --transport stdio k8s-ro \
  -- docker run --rm -i -v ~/.kube:/home/nonroot/.kube:ro ghcr.io/your-ko/mcp-k8s-ro:latest

建议在生产环境中固定使用特定版本（查看最新版本）：

claude mcp add --scope user --transport stdio k8s-ro \
  -- docker run --rm -i -v ~/.kube:/home/nonroot/.kube:ro ghcr.io/your-ko/mcp-k8s-ro:1.1.0

二进制文件

从 GitHub Releases 下载预构建的二进制文件：

# macOS Apple Silicon — change ARCH for other platforms: darwin-amd64, linux-amd64, linux-arm64
ARCH=darwin-arm64
VERSION=$(curl -fsSL https://api.github.com/repos/your-ko/mcp-k8s-ro/releases/latest | grep tag_name | cut -d'"' -f4)
curl -fsSL "https://github.com/your-ko/mcp-k8s-ro/releases/download/${VERSION}/mcp-k8s-ro-${VERSION}-${ARCH}" -o ~/.local/bin/mcp-k8s-ro
chmod +x ~/.local/bin/mcp-k8s-ro
xattr -d com.apple.quarantine ~/.local/bin/mcp-k8s-ro 2>/dev/null  # macOS only: remove Gatekeeper quarantine
claude mcp add --scope user --transport stdio k8s-ro ~/.local/bin/mcp-k8s-ro

macOS Gatekeeper：该二进制文件未经代码签名，因此 macOS 会阻止运行。 上面的 xattr 命令会移除隔离标记。或者，在首次被阻止后，前往“系统设置”→“隐私与安全性”，然后点击“仍要允许”。

也可以从源代码构建：

make build
claude mcp add --scope user --transport stdio k8s-ro ./bin/mcp-k8s-ro

自定义 kubeconfig 位置

如果你的 kubeconfig 不在 ~/.kube/config，请设置 KUBECONFIG 环境变量：

# Binary
claude mcp add --scope user --transport stdio -e KUBECONFIG=/path/to/kubeconfig k8s-ro ~/.local/bin/mcp-k8s-ro

# Docker
claude mcp add --scope user --transport stdio k8s-ro \
  -- docker run --rm -i -e KUBECONFIG=/config/kubeconfig -v /path/to/kubeconfig:/config/kubeconfig:ro ghcr.io/your-ko/mcp-k8s-ro:latest

单集群设计

该服务有意只使用一个 kubeconfig 上下文运行，并且不提供可在运行时切换集群的工具。原因如下：

• 提示词注入隔离——一个集群资源中的恶意值（例如 Pod 注释）无法指使 Claude 转向其他集群，包括生产集群。
• 明确的审计边界——每个工具响应都会包含上下文和集群名称，因此查询的是哪个集群始终清晰明确。

若要将服务指向其他集群，请停止服务、切换上下文，然后重启：

kubectl config use-context my-other-cluster
# then restart the MCP server / reload Claude Desktop

若要同时使用多个集群，请在 MCP 配置中为每个集群注册一个单独的服务实例：

{
  "mcpServers": {
    "k8s-staging": {
      "type": "stdio",
      "command": "/path/to/bin/mcp-k8s-ro",
      "env": { "KUBECONFIG": "/path/to/.kube/config" }
    },
    "k8s-prod": {
      "type": "stdio",
      "command": "/path/to/bin/mcp-k8s-ro",
      "env": { "KUBECONFIG": "/path/to/.kube/config-prod" }
    }
  }
}

Claude 会按名称调用每个服务，并且每个实例只能访问自己的集群。

MCP 注册表

此服务已发布在 registry.modelcontextprotocol.io