MCP Server Kubernetes

一个可以连接到 Kubernetes 集群并管理它的 MCP Server。支持按优先级顺序从多个来源加载 kubeconfig。

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

与 Claude Desktop 的使用

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

默认情况下，服务器会从 ~/.kube/config 加载 kubeconfig。有关额外的认证选项（环境变量、自定义路径等），请参阅 ADVANCED_README.md。

服务器将自动连接到您当前的 kubectl 上下文。请确保您拥有：

已安装 kubectl 并在 PATH 中
一个有效的 kubeconfig 文件，其中配置了上下文
对 Kubernetes 集群的访问权限（kubectl 已配置，例如 minikube、Rancher Desktop、GKE 等）
已安装 Helm v3 并在 PATH 中（无需 Tiller）。如果您不计划使用 Helm，则此步骤可选。

您可以通过让 Claude 列出您的 Pod 或创建一个测试部署来验证连接。

如果出现错误，请在标准终端中运行 kubectl get pods，以查看您是否可以在没有凭证问题的情况下连接到集群。

与 mcp-chat 的使用

mcp-chat 是一个用于 MCP 服务器的 CLI 聊天客户端。您可以使用它来与 Kubernetes 服务器交互。

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

或者，传递上面从 Claude Desktop 配置文件（Linux 应传递正确的路径到 config）：

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 集群
统一的 kubectl API 用于管理资源
- 使用 kubectl_get 获取或列出资源
- 使用 kubectl_describe 描述资源
- 使用 kubectl_get 列出资源
- 使用 kubectl_create 创建资源
- 使用 kubectl_apply 应用 YAML 资源清单
- 使用 kubectl_delete 删除资源
- 使用 kubectl_logs 获取日志
- 使用 kubectl_context 管理 kubectl 上下文
- 使用 explain_resource 解释 Kubernetes 资源
- 使用 list_api_resources 列出 API 资源
- 使用 kubectl_scale 缩放资源
- 使用 kubectl_patch 更新资源的字段
- 使用 kubectl_rollout 管理部署回滚
- 使用 kubectl_generic 执行任何 kubectl 命令
- 使用 ping 验证连接
高级操作
- 使用 kubectl_scale 缩放部署（替换旧的 scale_deployment）
- 使用 port_forward 将端口转发到 Pod 和服务
- 运行 Helm 操作
  - 安装、升级和卸载图表
  - 支持自定义值、存储库和版本
故障排除提示 (k8s-diagnose)
- 基于关键字和可选命名空间，提供系统的 Kubernetes 故障排除流程
非破坏性模式，用于对集群进行只读和创建/更新访问

提示

MCP Kubernetes 服务器包含专门的提示，以协助常见的诊断操作。

k8s-diagnose 提示

此提示提供了一个系统的 Kubernetes Pod 故障排除流程。它接受一个 keyword 来识别相关 Pod，并接受一个可选的 namespace 来缩小搜索范围。提示的输出将引导您进行自主故障排除流程，提供识别问题、收集证据和提出修复步骤的说明。

本地开发

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

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

开发工作流程

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

bun run dev

运行单元测试：

bun run test

构建项目：

bun run build

使用 Inspector 进行本地测试

npx @modelcontextprotocol/inspector node dist/index.js
# 按照终端中的进一步说明获取 Inspector 链接

使用 Claude Desktop 进行本地测试

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

使用 mcp-chat 进行本地测试

bun run chat

贡献

请参阅 CONTRIBUTING.md 文件了解详情。

高级

非破坏性模式

您可以在非破坏性模式下运行服务器，该模式禁用所有破坏性操作（删除 Pod、删除部署、删除命名空间等）：

ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true npx mcp-server-kubernetes

对于具有非破坏性模式的 Claude Desktop 配置：

{
  "mcpServers": {
    "kubernetes-readonly": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "env": {
        "ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS": "true"
      }
    }
  }
}

非破坏性模式下可用的命令

所有只读和资源创建/更新操作仍然可用：

资源信息：kubectl_get、kubectl_describe、kubectl_logs、explain_resource、list_api_resources
资源创建/修改：kubectl_apply、kubectl_create、kubectl_scale、kubectl_patch、kubectl_rollout
Helm 操作：install_helm_chart、upgrade_helm_chart
连接性：port_forward、stop_port_forward
上下文管理：kubectl_context

非破坏性模式下禁用的命令

以下破坏性操作被禁用：

kubectl_delete：删除任何 Kubernetes 资源
uninstall_helm_chart：卸载 Helm 图表
cleanup：清理管理资源
kubectl_generic：通用 kubectl 命令访问（可能包含破坏性操作）

有关其他高级功能，请参阅 ADVANCED_README.md。

架构

有关更深入的架构概述，请参阅由 Devin 创建的此 DeepWiki 链接。

本节描述了 MCP Kubernetes 服务器的整体架构。

请求流程

下面的时序图说明了请求如何通过系统流动：

sequenceDiagram
    participant Client
    participant Transport as Transport Layer
    participant Server as MCP Server
    participant Filter as Tool Filter
    participant Handler as Request Handler
    participant K8sManager as KubernetesManager
    participant K8s as Kubernetes API

    Note over Transport: StdioTransport 或<br>SSE Transport

    Client->>Transport: 发送请求
    Transport->>Server: 转发请求

    alt 工具请求
        Server->>Filter: 过滤可用工具
        Note over Filter: 如果处于非破坏性模式，则移除破坏性工具
        Filter->>Handler: 路由到工具处理器

        alt kubectl 操作
            Handler->>K8sManager: 执行 kubectl 操作
            K8sManager->>K8s: 进行 API 调用
        else Helm 操作
            Handler->>K8sManager: 执行 Helm 操作
            K8sManager->>K8s: 进行 API 调用
        else 端口转发操作
            Handler->>K8sManager: 设置端口转发
            K8sManager->>K8s: 进行 API 调用
        end

        K8s-->>K8sManager: 返回结果
        K8sManager-->>Handler: 处理响应
        Handler-->>Server: 返回工具结果
    else 资源请求
        Server->>Handler: 路由到资源处理器
        Handler->>K8sManager: 获取资源数据
        K8sManager->>K8s: 查询 API
        K8s-->>K8sManager: 返回数据
        K8sManager-->>Handler: 格式化响应
        Handler-->>Server: 返回资源数据
    end

    Server-->>Transport: 发送响应
    Transport-->>Client: 返回最终响应

有关更深入的架构概述，请参阅由 Devin 创建的此 DeepWiki 链接。

发布新版本

前往发布页面，点击“草拟新版本”，点击“选择标签”，通过输入新的版本号（使用 "v{major}.{minor}.{patch}" semver 格式）创建一个新标签。然后，输入发布标题 "Release v{major}.{minor}.{patch}"，如有必要，输入描述/变更日志，并点击“发布版本”。

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

未计划

添加集群到 kubectx。

星标历史

🖊️ 引用

如果您觉得这个仓库有用，请引用：

@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}
}

Flux159/mcp-server-kubernetes

星标增长

证据时间轴