MCP Server Kubernetes

MCP Server Kubernetes

可连接 Kubernetes 集群并对其进行管理的 MCP 服务。

https://github.com/user-attachments/assets/f25f8f4e-4d04-479b-9ae0-5dac452dd2ed

在 Claude Desktop 中使用

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

服务会自动连接到当前的 kubectl 上下文。请确保已满足以下条件：

1. 已安装 kubectl，且位于 PATH 中
2. 拥有有效的 kubeconfig 文件，并已配置上下文
3. 已配置 kubectl 访问 Kubernetes 集群（例如 minikube、Rancher Desktop、GKE 等）
4. 已安装 Helm v3，且位于 PATH 中（无需 Tiller）。如果不打算使用 Helm，此项为可选。

你可以让 Claude 列出 Pod 或创建测试部署，以验证连接。

如果遇到错误，请打开标准终端并运行 kubectl get pods，查看是否能在没有凭据问题的情况下连接到集群。

在 mcp-chat 中使用

mcp-chat 是一个用于 MCP 服务的命令行聊天客户端。你可以用它与 Kubernetes 服务交互。

npx mcp-chat --server "npx mcp-server-kubernetes"

或者，将上文中的 Claude Desktop 配置文件传给它（Linux 用户应传入正确的配置文件路径）：

Mac：

npx mcp-chat --config "~/Library/Application Support/Claude/claude_desktop_config.json"

Windows：

npx mcp-chat --config "%APPDATA%\Claude\claude_desktop_config.json"

功能

• 连接到 Kubernetes 集群
• 列出所有 Pod、服务、部署和节点
• 创建、描述和删除 Pod
• 列出所有命名空间，创建命名空间
• 创建自定义 Pod 和部署配置，更新部署副本数
• 创建服务
• 获取 Pod 日志以进行调试（支持 Pod、部署、作业和标签选择器）
• 支持使用 Helm v3 安装 Chart
  • 使用自定义值安装 Chart
  • 卸载发行版本
  • 升级现有发行版本
  • 支持命名空间
  • 支持指定版本
  • 支持自定义仓库
• 支持 kubectl explain 和 kubectl api-resources
• 获取集群中的 Kubernetes 事件
• 将端口转发到 Pod 或服务
• 创建、列出和描述 CronJob
• 非破坏性模式：仅允许读取以及创建/更新集群资源

本地开发

请确保已安装 bun。克隆仓库并安装依赖：

git clone https://github.com/Flux159/mcp-server-kubernetes.git
cd mcp-server-kubernetes
bun install

开发工作流

1. 以开发模式启动服务（监视文件更改）：

bun run dev

2. 运行单元测试：

bun run test

3. 构建项目：

bun run build

4. 使用 Inspector 进行本地测试

npx @modelcontextprotocol/inspector node dist/index.js
# Follow further instructions on terminal for Inspector link

5. 使用 Claude Desktop 进行本地测试

{
  "mcpServers": {
    "mcp-server-kubernetes": {
      "command": "node",
      "args": ["/path/to/your/mcp-server-kubernetes/dist/index.js"]
    }
  }
}

6. 使用 mcp-chat 进行本地测试

bun run chat

贡献

详情请参阅 CONTRIBUTING.md 文件。

进阶

其他高级功能

有关更多高级信息，例如使用 SSE 传输，以及通过 ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS 启用非破坏性模式，请参阅 ADVANCED_README.md。

架构

本节介绍 MCP Kubernetes 服务的高层架构。

请求流程

下方的时序图展示了请求在系统中的流转过程：

sequenceDiagram
    participant Client
    participant Transport as StdioTransport
    participant Server as MCP Server
    participant Handler as Request Handler
    participant K8sManager as KubernetesManager
    participant K8s as Kubernetes API

    Client->>Transport: Send Request via STDIO
    Transport->>Server: Forward Request

    alt Tools Request
        Server->>Handler: Route to tools handler
        Handler->>K8sManager: Execute tool operation
        K8sManager->>K8s: Make API call
        K8s-->>K8sManager: Return result
        K8sManager-->>Handler: Process response
        Handler-->>Server: Return tool result
    else Resource Request
        Server->>Handler: Route to resource handler
        Handler->>K8sManager: Get resource data
        K8sManager->>K8s: Query API
        K8s-->>K8sManager: Return data
        K8sManager-->>Handler: Format response
        Handler-->>Server: Return resource data
    end

    Server-->>Transport: Send Response
    Transport-->>Client: Return Final Response

发布新版本

前往 releases page，点击“Draft New Release”，再点击“Choose a tag”，然后输入新版本号并创建新标签，版本号采用“v{major}.{minor}.{patch}”语义化版本格式。接着，填写发布标题“Release v{major}.{minor}.{patch}”以及描述／变更日志（如有需要），然后点击“Publish Release”。

这将创建一个新标签，并通过 cd.yml 工作流触发新的发布构建。构建成功后，新版本将发布到 npm。请注意，无需手动更新 package.json 中的版本号，因为工作流会自动更新 package.json 文件中的版本号，并向 main 推送一次提交。

暂不计划

身份验证／向 kubectx 添加集群。