K8s MCP Server (Go)

k8s-mcp-go

默认安全、只读的 Kubernetes 访问，供 AI Agent 使用。

一个 Kubernetes MCP 服务，可让 AI 助手安全地检查集群，而无需授予其不受限制的 kubectl 权限。

与众不同之处

• 默认只读：便于诊断，无需赋予 AI 修改集群的权限。
• 明确的权限模式：在助手启动前选择 readonly、readwrite 或 dangerous。
• 无需 Docker：通过 MCPB bundle 或单个原生二进制文件安装。
• 原生 Kubernetes 可见性：检查 Pod、Deployment、Service、日志、事件、节点，以及实时 CPU／内存使用情况。
• 可用于注册表的分发方式：以 io.github.kaneg/k8s-mcp-go 发布，供 MCP Registry 用户和打包客户端使用。

分发

• MCP Registry：以 io.github.kaneg/k8s-mcp-go 发布。
• PulseMCP：通过官方 server.json 编入 MCP 生态索引。
• Claude Code Marketplaces：收录了 MCPB 安装元数据。

原因

大多数 AI Agent 都能使用 Kubernetes 工具。 真正的问题是如何防止它们误改资源。

授予 AI 原始 kubectl 访问权限存在风险。即使是能力很强的模型，也可能：

• 删除错误的资源
• 重启错误的工作负载
• 应用危险的更改
• 将调试会话变成生产事故

k8s-mcp-go 为 AI Agent 提供了一个带有防护措施的 Kubernetes 接口，而非不受限制的 Shell 访问权限。

它旨在解决这个现实问题：

如何让 AI 协助处理 Kubernetes，同时又不让它破坏我的集群？

权限模式

你可以预先选择权限边界：

你的需求	模式
“让 AI 检查和诊断，但不做任何更改”	readonly
“允许扩缩和重启等安全运维操作”	readwrite
“赋予它完整的集群权限”	dangerous

readonly（默认）

用于诊断、检查和安全探索。

AI 可以执行以下操作：

• 列出 Pod、Deployment、Service、节点和命名空间
• 读取日志和事件
• 检查集群状态
• 查看资源使用情况

它无法修改工作负载或删除资源。

readwrite

用于受控的运维工作流。

AI 可以执行以下操作：

• 扩缩 Deployment
• 重启 Deployment
• 重启 StatefulSet
• 更新镜像
• 修补 Deployment
• 创建命名空间

它仍然无法执行破坏性最大的操作。

dangerous

完整访问权限。

仅在你明确希望 AI 能够执行以下操作时使用：

• 删除资源
• 删除命名空间
• 应用任意 YAML

如果不确定，请使用 readonly。

快速开始

选项 1：安装 MCPB（推荐）

从 Releases 下载适用于你平台的 .mcpb bundle。兼容 MCPB 的客户端（Claude Desktop、Cursor 等）可以直接安装，无需 Docker、Go 或手动设置。

操作系统	架构	文件
Linux	x86_64	k8s-mcp-go_*_linux_amd64.mcpb
Linux	ARM64	k8s-mcp-go_*_linux_arm64.mcpb
macOS	Intel	k8s-mcp-go_*_darwin_amd64.mcpb
macOS	Apple Silicon	k8s-mcp-go_*_darwin_arm64.mcpb
Windows	x86_64	k8s-mcp-go_*_windows_amd64.mcpb
Windows	ARM64	k8s-mcp-go_*_windows_arm64.mcpb

选项 2：手动安装二进制文件

从 Releases 下载二进制压缩包并解压：

# Example: Linux x86_64
tar xzf k8s-mcp-go_*_linux_amd64.tar.gz
chmod +x k8s-mcp-go
sudo mv k8s-mcp-go /usr/local/bin/

然后将其添加到 MCP 客户端。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "k8s": {
      "command": "k8s-mcp-go",
      "args": ["-mode=readonly"]
    }
  }
}

Cursor（.cursor/mcp.json）：

{
  "mcpServers": {
    "k8s": {
      "command": "k8s-mcp-go",
      "args": ["-mode=readonly"]
    }
  }
}

重启客户端，然后开始询问有关集群的问题。

示例提示词

安装完成后，可以向 AI 助手提出如下问题：

• “显示所有命名空间中的异常 Pod。”
• “哪些 Pod 使用的内存最多？”
• “总结最近的警告事件。”
• “检查此部署，并说明它为何尚未就绪。”
• “检查此部署的发布状态。”

在 readonly 模式下，助手可以进行调查，但无法更改集群。

为什么不直接使用 kubectl？

因为问题不在于 AI 是否能与 Kubernetes 通信。 问题在于它能否安全地做到这一点。

kubectl 功能强大，但它没有为 AI 行为提供产品级权限模式。 使用 k8s-mcp-go，你可以决定助手是否能够：

• 仅进行检查
• 执行有限的运维操作
• 或获得完全控制权

权限边界就是产品本身。

可用工具（共 35 个）

工具按权限级别分组。 名称以 get、list 或 delete 等动作动词开头；top_nodes 和 top_pods 保留了 Kubernetes 中沿用的 kubectl top 术语。

只读（24 个）

工具	描述
get_server_info	显示服务版本、模式、Kubernetes 配置来源和运行时详情
resolve_workload	将应用/工作负载名称解析为匹配的资源，并提供建议使用的后续工具
list_pods	列出 Pod；支持 all_namespaces=true
get_pod	获取 Pod 详情
get_pod_logs	获取 Pod 日志
list_deployments	列出 Deployment；支持 all_namespaces=true
get_deployment	获取 Deployment 详情
list_statefulsets	列出 StatefulSet；支持 all_namespaces=true
get_statefulset	获取 StatefulSet 详情
list_services	列出 Service；支持 all_namespaces=true
get_service	获取 Service 详情
list_configmaps	列出 ConfigMap；支持 all_namespaces=true
get_configmap	获取 ConfigMap 数据
list_secrets	列出 Secret（仅显示键）；支持 all_namespaces=true
get_secret	获取 Secret 元数据和键
list_pvc	列出 PersistentVolumeClaim；支持 all_namespaces=true
list_ingress	列出 Ingress 资源；支持 all_namespaces=true
list_jobs	列出 Job；支持 all_namespaces=true
top_nodes	当前节点 CPU 和内存使用情况
top_pods	当前 Pod CPU 和内存使用情况
list_nodes	列出集群节点
list_namespaces	列出命名空间
get_cluster_overview	集群健康状况摘要
list_events	列出事件

读写（7 个）

工具	描述
scale_deployment	调整 Deployment 副本数
restart_deployment	滚动重启 Deployment
restart_statefulset	滚动重启 StatefulSet
set_image	更新容器镜像
get_rollout_status	检查发布进度
create_namespace	创建新命名空间
patch_deployment	应用战略合并补丁

危险（7 个）

工具	描述
delete_pod	删除 Pod
delete_deployment	删除 Deployment
delete_statefulset	删除 StatefulSet 及其 Pod
delete_daemonset	删除 DaemonSet 及其 Pod
delete_resource	删除没有专用删除工具的资源
delete_namespace	删除命名空间及其所有资源
apply_yaml	应用任意 YAML 清单

如果上面有专用删除工具，请优先使用。对于其他类型的资源，请使用 delete_resource 作为备用工具。它会通过 Kubernetes 发现机制解析资源属于命名空间级还是集群级。

{"api_version":"v1","kind":"ServiceAccount","namespace":"apps","name":"builder"}
{"api_version":"rbac.authorization.k8s.io/v1","kind":"ClusterRole","name":"auditor"}

Kubernetes 配置

配置按以下顺序选择：

1. 设置了 KUBECONFIG 时指定的文件。
2. Pod 的集群内 ServiceAccount 配置。
3. 在集群外运行时使用 ~/.kube/config。

显式指定的 KUBECONFIG 具有权威性。如果无法加载，服务会返回错误，而不会静默切换到 Pod 的 ServiceAccount。 集群内配置使用 Kubernetes 挂载的令牌文件，因此投射的 ServiceAccount 令牌轮换可以继续生效，无需将令牌复制到 kubeconfig 中。

环境变量

变量	描述
KUBECONFIG	显式指定的 kubeconfig 路径。未设置时，使用集群内配置，或回退到 ~/.kube/config。

从源代码构建

git clone https://github.com/kaneg/k8s-mcp-go.git
cd k8s-mcp-go
go build -o k8s-mcp-go .

许可证

MIT