kubectl-mcp

一个 MCP（模型上下文协议） 服务器，让 AI 代理可以用自然语言检查 Kubernetes 集群——问 “哪些 Pod 在过去一小时内重启过？” 就能得到真实答案。

由 Teresa Tran 构建。

为什么

LLM 助手擅长解释 kubectl 命令，却不擅长安全地实际运行它们。kubectl-mcp 将只读的集群检查功能暴露为一组代理可以调用的 MCP 工具——将“检查我的集群”从复制粘贴加祈祷变成真正的对话。

• 设计上只读。 没有 apply、delete、exec。服务器只进行 检查。

• 默认模拟模式。 附带一个预置的假集群，让你无需真实集群即可在 30 秒内试用。

• 随时切换到真实模式。 指向你的 KUBECONFIG，它就会通过官方 Kubernetes Python 客户端查询真实集群。

Related MCP server: Kubernetes MCP Server

安装

pip install kubectl-mcp                # mock mode (default)
pip install "kubectl-mcp[real]"        # + real-cluster support (kubernetes client)

或者从源码安装：

git clone https://github.com/teresa-tran/kubectl-mcp.git
cd kubectl-mcp
pip install -e ".[real,dev]"

独立运行（冒烟测试）

kubectl-mcp --help                     # show flags
kubectl-mcp --list-tools               # print every MCP tool + its schema
kubectl-mcp --demo list_pods           # run a tool once against the mock cluster
kubectl-mcp --demo find_restarted_pods --arg since_minutes=120

接入 MCP 客户端

Claude Desktop

在 ~/Library/Application Support/Claude/claude_desktop_config.json（mac）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）中添加：

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp"
    }
  }
}

对于真实集群模式：

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp",
      "env": {
        "KUBECTL_MCP_MODE": "real",
        "KUBECONFIG": "/Users/you/.kube/config"
      }
    }
  }
}

重启 Claude Desktop。现在你应该可以问 “列出 production 命名空间中的 Pod” 并得到真实答案。

其他兼容 MCP 的客户端

任何支持 stdio MCP 的客户端（Cursor、Cline、Continue、自定义代理）都以相同方式工作——将其指向 kubectl-mcp 二进制文件即可。

暴露的工具

每个工具都有 JSON Schema——LLM 可以免费获得正确的参数验证。

配置

环境变量：

模拟集群

默认的模拟集群位于 src/kubectl_mcp/mock_data.json，包含：

• 3 个命名空间：default、production、staging

• ~15 个 Pod，涵盖健康、崩溃循环和最近重启状态

• 部署、服务和一系列最近事件

• 一些 Pod 的重启次数 > 0，因此 find_restarted_pods 会返回真实结果

你可以通过设置 KUBECTL_MCP_MOCK_DATA=/path/to/your.json 来覆盖它，以便演示特定场景。

设计说明

• 构造上只读。 KubernetesBackend 协议只定义读取方法。没有任何代码路径可以修改集群状态——即使在真实模式下也是如此。

• 后端可替换。 MockBackend 和 RealBackend 实现相同的协议。添加第三个（例如缓存快照）只需一个文件。

• 错误是异常，不是静默的 null。 ResourceNotFound、NamespaceNotFound 等会作为 McpError 传播，并带有有用的消息，以便代理进行纠正。

• stdio 传输。 所有 MCP 工具调用都是通过 stdio 的 JSON-RPC，完全符合 MCP 规范。

开发

pip install -e ".[real,dev]"
pytest                                 # run tests
ruff check src tests                   # lint
kubectl-mcp --demo list_pods --arg namespace=production   # smoke test

路线图

• 带种子数据的模拟后端

• 通过 kubernetes Python 客户端的真实后端

• 只读工具表面

• 用于 CI/冒烟测试的独立 --demo 模式

• 多集群支持（--context 标志）

• 指标工具（通过 metrics.k8s.io 获取 CPU/内存）

• 用于高频查询的可选缓存层

许可证

MIT © 2026 Teresa Tran