进阶 约 25 分钟 2026-10-21 02:03:50 · 39 阅读

kubernetes-mcp-server 接入实操:20 个工具让 AI 在聊天框里管集群

管集群这件事,kubectl 之外还有一条聊天框路线

凌晨两点收到告警,你打开终端敲 kubectl get pods -A、再 kubectl logs、再 kubectl describe——这是运维的日常。kubernetes-mcp-server 把这些动作搬进 MCP 客户端:接入之后,你在 Claude Desktop、Cursor 或 VS Code 的对话框里说「看一下 default 命名空间里哪些 Pod 不是 Running」,AI 会自己调工具去查。这篇文章从安装、启动检查、工具清单到安全护栏完整走一遍,每一步的输出都来自真实运行,报错也原样保留。

项目由 containers 组织维护(就是 Podman 背后的团队),GitHub 上两千余星,以官方页面为准。它和市面上多数 Kubernetes MCP 服务器最大的区别写在 README 第一屏:这不是一个包 kubectl 命令行的壳子,而是 Go 原生实现,直接对接 Kubernetes API Server,宿主机上不需要装 kubectl、helm 或者任何外部工具。读写入口见 AI 工具总纲,Kubernetes 产品档案在 产品页。

kubernetes-mcp-server 默认 20 个工具全景分组图

v0.0.67 实测 tools/list 的 20 个工具按 resources / pods / nodes / 其他四组整理,名字与参数以实测返回为准

装之前先确认两件事

第一件:你手上要有一个能连的 Kubernetes 集群。这不是客套话——README 的 Requirements 一节只写了一行「Access to a Kubernetes cluster」,而服务器把它当硬门槛。本机没有 kubeconfig 时直接启动,进程会立刻退出并给出这样的提示:

Error: unable to create kubernetes target provider: no current-context is set
and no contexts are defined in kubeconfig.
Configure a context with 'kubectl config set-context <name>' and
'kubectl config use-context <name>'

第二件:选一条安装路径。同一个包发了四种形态,效果等价:npm 包(npx -y kubernetes-mcp-server@latest,写稿时实测版本 0.0.67,PyPI 同步发版)、Python 包(uvx kubernetes-mcp-server)、Docker 镜像(docker run -i --rm ghcr.io/containers/kubernetes-mcp-server:v0.0.67),以及 Linux/macOS/Windows 的原生单文件二进制——用二进制的话机器上连 Node 和 Python 都不用装。用 npx 的话注意 npm 与 Node 版本的匹配警告:本机 Node v20.16.0 配 npm 10.8.1 能正常拉起,只有一行版本支持提示,不影响运行。

把服务器挂进你的客户端

Claude Desktop 用户改 claude_desktop_config.json,在 mcpServers 里加一段:

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest"]
    }
  }
}

Cursor 是编辑 mcp.json,键名换成 kubernetes-mcp-server,结构相同。VS Code 与 VS Code Insiders 走扩展安装链接,或者一条命令搞定:code --add-mcp '{"name":"kubernetes","command":"npx","args":["kubernetes-mcp-server@latest"]}'。用 Goose 的读者在 config.yaml 的 extensions 段落里写同样的 command 与 args。以上四段配置原文都出自仓库 README 的 Getting Started 一节,可以直接对照抄。

配置保存后重启客户端,服务器会以 stdio 方式被拉起。第一次连接时握手信息长这样(实测原文):

serverInfo: {"name": "kubernetes-mcp-server", "title": "kubernetes-mcp-server",
"version": "v0.0.67", "websiteUrl": "https://github.com/containers/kubernetes-mcp-server"}

20 个工具够不够用

握手成功后调 tools/list,v0.0.67 默认返回 20 个工具。数量本身不算多,但覆盖面是按「运维高频动作」设计的:通用资源走 resources_* 五件套(按 apiVersion+kind 增删改查加扩缩容),Pod 侧有列表、取详情、删、看日志、exec 进容器、临时跑镜像共八个,节点侧三个(系统日志、资源用量、kubelet Summary 统计),再加事件、命名空间、OpenShift 项目和一个 kubeconfig 导出工具。所有需要 RBAC 授权的工具都在返回的 _meta 字段里声明了权限需求,格式见仓库 docs/tool-rbac-metadata.md——客户端可以据此在调用前临时创建最小权限的 ServiceAccount,文档里特别强调这只是规划辅助,最终裁定权仍在 Kubernetes API Server。

无 kubeconfig 启动报错与最小 kubeconfig 实测流程图

两条启动路径的实测记录:无 kubeconfig 直接退出;用一个指向本地假地址的最小 kubeconfig 可以完成握手和 tools/list,调用集群类工具时如实回错

这里有一个值得单独说的实测细节。没接真集群也想验证安装的话,可以准备一个 server 指向 127.0.0.1:64431 的最小 kubeconfig(本机并没有监听这个端口):用它启动服务器,握手正常、tools/list 正常返回 20 个工具——说明启动检查只验证 kubeconfig 结构,不验证连通性。随后调用 namespaces_list 和 pods_list,两个调用都以 isError=true 结束,错误原文是:

failed to list namespaces: Get "https://127.0.0.1:64431/api?timeout=10s":
dial tcp 127.0.0.1:64431: connect: connection refused

报错里带完整的目标地址和十秒超时参数。这个行为对排障很友好:AI 收到的是明确失败原因而不是空结果,顺着地址就能查到是网络、证书还是 kubeconfig 指错的问题。

素材清单和实测对不齐,怎么办

网上流传的「kubernetes-mcp-server 工具清单」(包括选题素材包里的那份)大多把 README 特性区的能力全列了进去:helm_install、tekton_pipeline_start 之类。实测默认清单里并没有它们——因为工具是按 toolset 分组的,默认只开 core 和 config 两组。反过来说,实测清单里的 nodes_log、nodes_top、pods_list_in_namespace、resources_scale 这些,又常被整理者漏掉。

素材清单与实测 tools/list 差异对照表

两份「20 个工具」的出入逐条对照:清单多列了默认关闭的 Helm/Tekton,漏了实测存在的 nodes/resources_scale 等

结论很实际:接入之后先在自己环境里跑一次 tools/list,以返回结果为准,别背任何二手清单。想知道还差哪些能力,就看下面这张 toolset 全表。

12 个 toolset,按需打开

12 个 toolset 状态表

官方配置文档的 Toolsets 全表:绿色两行默认开启,其余十个按需开启(依据 docs/configuration.md 摘译)

开关机制在官方配置文档 docs/configuration.md 里写得很清楚。默认值是 toolsets = ["core", "config"];要加 Helm 和 KubeVirt,就写一行 toolsets = ["core", "config", "helm", "kubevirt"]。配置文件支持 drop-in 目录(conf.d 下按文件名字典序叠加),改完不用重启进程——给进程发一个 SIGHUP 信号,它会重新读配置、重建工具注册表并打日志记录每一项变化;只有 TLS 之类的少数非热加载项变更才会被拒绝并要求重启。文档原话点明了设计意图:只开需要的 toolset 可以压缩上下文体积、提高模型选工具的准确率。

toolset 之外还有两级细粒度控制:enabled_tools 白名单和 disabled_tools 黑名单,黑名单在白名单之后生效。一个值得注意的细节:configuration_view 这个工具在 HTTP 模式下默认被禁,因为它会把 kubeconfig 内容原样吐出来——想在 HTTP 模式用它,必须显式写进 enabled_tools,属于官方故意设置的「多想一步」开关。

三条护栏,接生产前必须过目

把一个能删 Pod 的 AI 接到生产集群,安全配置比功能更重要。这个项目在配置文档里提供了三层防线:

只读模式。TOML 里一行 read_only = true,写操作全部拒绝。官方 Kubernetes 接入指南(docs/getting-started-kubernetes.md)推荐的生产姿势正是「专用 ServiceAccount + 只读 RBAC + 只读模式」三件套,指南里附了完整的 Role 与 RoleBinding 清单可以照抄。

破坏性操作确认。--disable-destructive 启动参数之外,配置里还能给单个工具挂确认规则,文档给的示例就是 tool = "helm_uninstall"、message 写「This will uninstall a Helm release.」——命中规则的高危调用会被拦下来要求人工确认,而不是直接执行。

命令行级防线。deny_exec_commands 可以按正则拒绝 pods_exec 里跑的命令,防止 AI 在容器里执行危险操作。这三层叠加,才是一个敢接到共享集群上的形态。

日常用起来是什么样

接好之后的典型循环大概是这样:早晨到工位,问一句「昨天晚上有哪些 Warning 级别的 Event」,AI 调 events_list;顺着事件定位到 Pod,pods_get 看详情、pods_log 拉日志;发现是内存溢出,pods_top 看一周用量趋势;要临时验证修复,pods_run 起一个诊断镜像。整个过程不需要记命令行参数,自然语言描述意图即可。

多集群用户还有个彩蛋:kubeconfig 里定义的所有 context 都能同时访问,AI 会按目标资源的命名空间自动选择。想管 KubeVirt 虚拟机、查 Loki 日志、调 Tekton 流水线的,对应开 toolset 就行。

这些限制提前知道

其一,默认 20 个工具不含 Helm 与 Tekton,别在客户端里硬调 helm_list——工具不存在会直接报 Tool not found,先改配置开 toolset。其二,HTTP 模式(--port 8080 起的 Streamable HTTP 服务)默认禁用 configuration_view,这是有意的安全取舍。其三,pods_top 和 nodes_top 依赖集群装了 Metrics Server,没装的话这两个工具会报指标不可用,属于环境前提而非服务器缺陷。其四,Node 20 下 npm 只给版本匹配警告、不拦截安装,但环境太旧时 npx 拉包阶段就可能失败,遇到先查 Node 版本。其五,多租户场景(比如给团队每人一个沙箱)建议配合 tool-rbac-metadata.md 里的 RBAC 声明做权限收敛,文档明说这个声明不保证调用成功、只帮客户端提前准备权限。

来源与延伸

本文步骤与配图依据 kubernetes-mcp-server 官方仓库 README 与 docs/configuration.md、docs/tool-rbac-metadata.md 整理,实测记录来自 v0.0.67(2026-10-21,Node v20.16.0 环境),版权归原作者所有。

评论 (0)