Flux159/mcp-server-kubernetes

MCP Server Kubernetes – 基于 AI 的 Kubernetes 控制

是什么 – 一个轻量级的 Node 风格服务器（通过 npx mcp-server-kubernetes 运行），支持 Model Context Protocol（MCP）。它允许 AI 驱动的助手（Claude、Codex、VS Code 扩展、Cursor 等）发出类似 kubectl 的命令、Helm 操作、端口转发、节点维护和诊断指令，直接作用于本地 Kubernetes 集群。

为何重要 – 通过标准 MCP 接口暴露 Kubernetes 操作，开发者可以要求 LLM 执行 列出 Pod、应用清单、扩展部署 或 排查失败的 Pod 等任务，而无需编写任何 CLI 代码。该服务器可运行在只读模式以确保安全，并可选择性地输出 OpenTelemetry 跟踪数据以实现可观测性。

快速入门

前置条件 – 安装 kubectl、有效的 ~/.kube/config，以及（可选）Helm v3。安装 Bun 运行时（bun.sh）。

运行 –

bun install          # 安装依赖
npx mcp-server-kubernetes   # 启动服务器（STDIO 或 SSE 传输）

连接 AI 客户端 – 例如 Claude 桌面版、VS Code MCP 扩展，或 mcp-chat CLI：
```
npx mcp-chat --server "npx mcp-server-kubernetes"
```
客户端将自动识别当前的 kubectl 上下文。

核心功能（作为 MCP 工具暴露）

类别	工具（示例）	描述
资源增删改查	`kubectl_get`, `kubectl_create`, `kubectl_apply`, `kubectl_delete`	列出、创建、应用 YAML 或删除任何 K8s 对象。
检查	`kubectl_describe`, `kubectl_logs`, `explain_resource`	详细描述、日志尾部输出、自然语言解释。
管理	`kubectl_scale`, `kubectl_patch`, `kubectl_rollout`, `node_management`	扩展部署、修补字段、控制发布、隔离/驱逐节点。
Helm	`install_helm_chart`, `upgrade_helm_chart`, `helm_template_apply`, `helm_template_uninstall`	安装/升级图表，或渲染后应用模板以避免认证问题。
端口转发	`port_forward`, `stop_port_forward`	将 Pod/服务本地暴露。
诊断	`k8s-diagnose`	针对问题 Pod 的引导式排错流程。
工具	`kubectl_context`, `list_api_resources`, `ping`	切换上下文、列出 API 组、健康检查。

所有工具均可在 非破坏性模式 下过滤（ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true），仅保留只读和安全的创建/更新操作。

可观测性（可选）

通过环境变量启用：

export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
npx mcp-server-kubernetes

每个工具调用都会记录追踪信息（名称、持续时间、成功/失败、K8s 上下文等），并可导出至任何 OTLP 兼容后端（Jaeger、Grafana Tempo、Datadog、AWS X‑Ray 等）。
详见 docs/OBSERVABILITY.md 了解采样、配置和部署示例。

开发与贡献

构建 – bun run dev（监听模式）、bun run test、bun run build。
本地测试 – 使用 Model Context Protocol 的 inspector 或内置的 mcp-chat CLI。
贡献 – 参照 CONTRIBUTING.md；欢迎提交 PR。
发布流程 – 在 GitHub 上打新的 vX.Y.Z 标签；CI 会自动构建并发布 npm 包。

适用人群

AI 辅助开发人员，希望其 LLM 能直接从编辑器管理集群。
运维团队，构建需要安全、可审计 Kubernetes 操作的聊天运维机器人。
工具开发者，寻找可与 Claude、Cursor 或自定义助手集成的 MCP 兼容后端。

引用

如引用该项目，请使用以下 BibTeX 条目：

@software{Patel_MCP_Server_Kubernetes_2024,
  author = {Patel, Paras and Sonwalkar, Suyog},
  month = jul,
  title = {{MCP Server Kubernetes}},
  url = {https://github.com/Flux159/mcp-server-kubernetes},
  version = {2.5.0},
  year = {2024}
}