Skip to main content
Glama
kubectl-mcp

kubectl-mcp

by teresa-tran

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 二进制文件即可。

暴露的工具

工具

功能

list_namespaces

集群中的所有命名空间

list_pods

命名空间中的 Pod,包含阶段和重启次数

get_pod

单个 Pod 的完整详情(容器、状态、事件)

list_deployments

命名空间中的部署,包含就绪/期望副本数

get_deployment

单个部署的完整详情

list_services

命名空间中的服务,包含类型和端点

list_recent_events

最近 N 分钟内的事件,最新的在前

get_pod_logs

Pod 日志的最后 N 行(只读,无 exec)

find_restarted_pods

最近 N 分钟内重启过的 Pod(高级查询)

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

配置

环境变量:

变量

值

默认值

说明

KUBECTL_MCP_MODE

mock | real

mock

集群后端

KUBECONFIG

path

~/.kube/config

真实模式的 kubeconfig 路径

KUBECTL_MCP_MOCK_DATA

path

(bundled)

覆盖模拟集群 JSON

KUBECTL_MCP_LOG_LEVEL

debug | info | warn

info

日志详细程度(输出到 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

路线图

  • 带种子数据的模拟后端

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

  • 只读工具表面

  • 用于 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…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Provides 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.
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      6
      38 npm
      MIT