kubectl-mcp
kubectl-mcp
一个 MCP(模型上下文协议) 服务器,让 AI 代理可以用自然语言检查 Kubernetes 集群——问 “哪些 Pod 在过去一小时内重启过?” 就能得到真实答案。
由 Teresa Tran 构建。
为什么
LLM 助手擅长解释 kubectl 命令,却不擅长安全地实际运行它们。kubectl-mcp 将只读的集群检查功能暴露为一组代理可以调用的 MCP 工具——将“检查我的集群”从复制粘贴加祈祷变成真正的对话。
设计上只读。 没有
apply、delete、exec。服务器只进行 检查。默认模拟模式。 附带一个预置的假集群,让你无需真实集群即可在 30 秒内试用。
随时切换到真实模式。 指向你的
KUBECONFIG,它就会通过官方 Kubernetes Python 客户端查询真实集群。
Related MCP server: mcp-k8s-context-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 二进制文件即可。
暴露的工具
工具 | 功能 |
| 集群中的所有命名空间 |
| 命名空间中的 Pod,包含阶段和重启次数 |
| 单个 Pod 的完整详情(容器、状态、事件) |
| 命名空间中的部署,包含就绪/期望副本数 |
| 单个部署的完整详情 |
| 命名空间中的服务,包含类型和端点 |
| 最近 N 分钟内的事件,最新的在前 |
| Pod 日志的最后 N 行(只读,无 |
| 最近 N 分钟内重启过的 Pod(高级查询) |
每个工具都有 JSON Schema——LLM 可以免费获得正确的参数验证。
配置
环境变量:
变量 | 值 | 默认值 | 说明 |
|
|
| 集群后端 |
| path |
| 真实模式的 kubeconfig 路径 |
| path | (bundled) | 覆盖模拟集群 JSON |
|
|
| 日志详细程度(输出到 stderr) |
模拟集群
默认的模拟集群位于 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路线图
带种子数据的模拟后端
通过
kubernetesPython 客户端的真实后端只读工具表面
用于 CI/冒烟测试的独立
--demo模式多集群支持(
--context标志)指标工具(通过
metrics.k8s.io获取 CPU/内存)用于高频查询的可选缓存层
许可证
MIT © 2026 Teresa Tran
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Fail-closed policy guardrails for AI agents running kubectl, terraform, helm, and argocd.
The Google GKE MCP server is a managed Model Context Protocol server that provides AI applications with tools to manage Google Kubernetes Engine (GKE) clusters and Kubernetes resources. It exposes a structured, discoverable interface that allows AI agents to interact with GKE and Kubernetes APIs, enabling them to inspect cluster configurations, retrieve Kubernetes resource YAMLs, monitor operations like cluster upgrades, diagnose issues, and optimize costs—all without needing to parse text output or use complex kubectl commands.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
Unified API to query AWS, GCP, Azure and generate Terraform/CLI execution kits for AI agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceExposes Kubernetes cluster management tools to LLMs, enabling querying pods, deployments, logs, metrics, and managing port forwards via natural language.1-
- FlicenseNot gradedqualityDmaintenanceProvides a read-only interface to Kubernetes clusters, enabling LLMs to list pods, get pod status and logs, fetch deployment manifests, and perform pod health analysis with resource trend tracking.-
- FlicenseNot gradedqualityCmaintenanceProvides read-only Kubernetes cluster operations via MCP, enabling LLMs to query nodes, pods, logs, events, and watch real-time status for troubleshooting.2-
- AlicenseAqualityBmaintenanceEnables AI agents to explore and operate OpenShift/Kubernetes clusters, offering read-only tools for projects, pods, logs, and resources, with opt-in higher modes for scaling, restarts, applying manifests, and deletions under safe-by-default guards.638 npmMIT