MCP Server Kubernetes

一个可连接 Kubernetes 集群并对其进行管理的 MCP Server（Model Context Protocol Server，模型上下文协议服务器）。支持按优先级顺序从多个来源加载 kubeconfig。

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

安装与使用

先决条件

在将此 MCP server 与任何工具配合使用之前，请确保您已满足以下条件：

1. 已安装 kubectl 并将其加入 PATH
2. 拥有一个配置了上下文（contexts）的有效 kubeconfig 文件
3. 能通过 kubectl 访问 Kubernetes 集群（例如 minikube、Rancher Desktop、GKE 等）
4. 已安装 Helm v3 并将其加入 PATH（无需 Tiller）。如果您不打算使用 Helm，则此项为可选。

您可以通过在终端中运行 kubectl get pods 来验证连接，确保能够无凭证问题地连接到集群。

默认情况下，该 server 会从 ~/.kube/config 加载 kubeconfig。如需其他认证选项（环境变量、自定义路径等），请参阅 ADVANCED_README.md。

Claude Code

使用内置命令将 MCP server 添加到 Claude Code：

claude mcp add kubernetes -- npx mcp-server-kubernetes

这将自动在您的 Claude Code MCP 设置中配置该 server。

Claude Desktop

将以下配置添加到您的 Claude Desktop 配置文件中：

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

通过 mcpb 使用 Claude Desktop Connector

MCP Server Kubernetes 也可作为 mcpb（原名 dxt）扩展使用。在 Claude Desktop 中，进入设置（Mac 上为 Cmd+,）→ Extensions（扩展）→ Browse Extensions（浏览扩展），在弹窗中滚动查找 mcp-server-kubernetes 并安装。安装后，它将通过命令行自动安装并使用 kubectl 及您的 kubeconfig。

您也可以手动安装：前往最新的 Release 页面下载 .mcpb 文件。

VS Code

对于 VS Code 集成，您可以将该 MCP server 与支持 Model Context Protocol 的扩展一起使用：

1. 安装兼容的 MCP 扩展（例如 Claude Dev 或其他 MCP 客户端）
2. 配置该扩展以使用本 server：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["mcp-server-kubernetes"],
      "description": "Kubernetes 集群管理与操作"
    }
  }
}

Cursor

Cursor 通过其 AI 集成功能支持 MCP servers。将该 server 添加到您的 Cursor MCP 配置中：

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

该 server 将自动连接到您当前的 kubectl 上下文。您可以通过让 AI 助手列出您的 Pods 或创建一个测试 Deployment 来验证连接是否成功。

与 mcp-chat 配合使用

mcp-chat 是一个用于与 MCP servers 交互的 CLI 聊天客户端。您可以使用它来与 Kubernetes server 进行交互。

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"

Gemini CLI

Gemini CLI 允许您将 MCP servers 作为扩展安装。在终端中，通过指向本仓库来安装扩展：

gemini extensions install https://github.com/Flux159/mcp-server-kubernetes

功能特性

• 连接到 Kubernetes 集群
• 统一的 kubectl API 用于管理资源
  • 使用 kubectl_get 获取或列出资源
  • 使用 kubectl_describe 描述资源
  • 使用 kubectl_get 列出资源
  • 使用 kubectl_create 创建资源
  • 使用 kubectl_apply 应用 YAML 清单
  • 使用 kubectl_delete 删除资源
  • 使用 kubectl_logs 获取日志
  • 使用 kubectl_context 管理 kubectl 上下文（context）
  • 使用 explain_resource 解释 Kubernetes 资源
  • 使用 list_api_resources 列出 API 资源
  • 使用 kubectl_scale 扩缩资源
  • 使用 kubectl_patch 更新资源的字段
  • 使用 kubectl_rollout 管理 Deployment 的滚动更新
  • 使用 kubectl_generic 执行任意 kubectl 命令
  • 使用 ping 验证连接
• 高级操作
  • 使用 kubectl_scale 扩缩 Deployment（替代旧版 scale_deployment）
  • 使用 port_forward 对 Pod 和 Service 进行端口转发
  • Helm 操作支持
    • 安装、升级和卸载 Helm Chart
    • 支持自定义 values、仓库和版本
    • 基于模板的安装（helm_template_apply），可绕过认证问题
    • 基于模板的卸载（helm_template_uninstall），可绕过认证问题
  • Pod 清理操作
    • 清理处于以下状态的问题 Pod（cleanup_pods）：Evicted（已驱逐）、ContainerStatusUnknown（容器状态未知）、Completed（已完成）、Error（错误）、ImagePullBackOff（镜像拉取失败）、CrashLoopBackOff（崩溃循环）
  • 节点管理操作
    • 对节点进行封锁（cordon）、排空（drain）和解除封锁（uncordon）（node_management），用于维护和扩缩容操作
• 故障排查提示（k8s-diagnose）
  • 根据关键字和可选的命名空间（namespace），引导用户对 Pod 进行系统化的 Kubernetes 故障排查流程。
• 非破坏性模式（Non-destructive mode），仅允许对集群进行读取和创建/更新操作
• 敏感信息掩码（Secrets masking）以保障安全（在 kubectl get secrets 命令中屏蔽敏感数据，不影响日志）
• OpenTelemetry 可观测性（可选启用）
  • 为所有工具调用提供分布式追踪（Distributed tracing）
  • 支持导出到 Jaeger、Tempo、Grafana 或任意 OTLP 后端
  • 可配置的采样策略
  • 丰富的 Span 属性（工具名称、持续时间、K8s 上下文、错误信息等）
  • 详情请参阅 docs/OBSERVABILITY.md

可观测性

MCP Kubernetes 服务器包含可选的 OpenTelemetry 集成，用于全面的可观测性。该功能默认禁用，可通过环境变量或 Helm 配置启用。

快速开始

通过环境变量启用可观测性：

export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317

npx mcp-server-kubernetes

追踪内容

• 所有工具调用：如 kubectl_get、kubectl_apply、kubectl_logs 等
• 执行耗时：每次操作所花费的时间
• 成功/失败状态：自动错误追踪
• Kubernetes 上下文：命名空间、上下文、资源类型
• 丰富元数据：主机、进程和自定义属性

支持的后端

兼容任意 OTLP 后端：

• Jaeger（开源）
• Grafana Tempo（开源）
• Grafana Cloud（商业）
• Datadog、New Relic、Honeycomb、Lightstep、AWS X-Ray

配置

详见 docs/OBSERVABILITY.md，包括：

• 配置选项
• 部署示例（Kubernetes、Helm、Claude Code）
• 采样策略
• 生产环境最佳实践
• 故障排查指南

Jaeger 示例

# 启动 Jaeger
docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 4317:4317 \
  jaegertracing/all-in-one:latest

# 启用遥测
export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_TRACES_SAMPLER=always_on

# 启动服务器
npx mcp-server-kubernetes

# 查看追踪：http://localhost:16686

提示（Prompts）

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

开发工作流

1. 以开发模式启动服务器（监听文件变更）：

bun run dev

2. 运行单元测试：

bun run test

3. 构建项目：

bun run build

4. 使用 Inspector 进行本地测试

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

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 文件。

高级功能

非破坏性模式

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

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、helm_template_apply、helm_template_uninstall
• 连通性：port_forward、stop_port_forward
• 上下文管理：kubectl_context

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

以下破坏性操作已被禁用：

• kubectl_delete：删除任意 Kubernetes 资源
• uninstall_helm_chart：卸载 Helm chart
• cleanup：清理托管资源
• cleanup_pods：清理有问题的 Pod
• node_management：节点管理操作（可能排空节点）
• kubectl_generic：通用 kubectl 命令访问（可能包含破坏性操作）

如需了解其他高级功能，请参阅 ADVANCED_README.md 以及 docs 目录，其中包含关于 helm_install、helm_template_apply、节点管理与 Pod 清理的具体信息。

架构

有关更深入的架构概览（由 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 or<br>SSE Transport

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

    alt Tools Request
        Server->>Filter: Filter available tools
        Note over Filter: Remove destructive tools<br>if in non-destructive mode
        Filter->>Handler: Route to tools handler

        alt kubectl operations
            Handler->>K8sManager: Execute kubectl operation
            K8sManager->>K8s: Make API call
        else Helm operations
            Handler->>K8sManager: Execute Helm operation
            K8sManager->>K8s: Make API call
        else Port Forward operations
            Handler->>K8sManager: Set up port forwarding
            K8sManager->>K8s: Make API call
        end

        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

有关更深入的架构概览（由 Devin 创建），请参见此 DeepWiki 链接。

发布新版本

前往 releases 页面，点击 “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 添加集群。

Star 历史

🖊️ 引用

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

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

mcp-server-kubernetes 快速上手指南

环境准备

在使用 mcp-server-kubernetes 前，请确保满足以下条件：

1. kubectl 已安装并加入系统 PATH
   （国内用户可从 阿里云镜像 或 清华镜像站 下载）
2. 有效的 kubeconfig 文件（默认位于 ~/.kube/config），且已配置好集群上下文
3. 可通过 kubectl get pods 正常访问目标 Kubernetes 集群（如 Minikube、Rancher Desktop、ACK、GKE 等）
4. （可选）如需使用 Helm 功能，请安装 Helm v3（无需 Tiller）

💡 提示：若在国内网络环境，建议配置 kubectl 和 Helm 的国内镜像源以加速下载。

安装步骤

该工具基于 Node.js 生态，可通过 npx 直接运行，无需全局安装：

# 验证是否可正常启动（会自动下载并运行）
npx mcp-server-kubernetes

如需在特定 AI 开发环境中集成，请参考对应配置方式：

VS Code / Claude Desktop / Cursor 配置

在 MCP 客户端配置文件中添加以下内容：

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

使用 mcp-chat 本地测试

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

基本使用

启动后，AI 助手即可通过 MCP 协议调用 Kubernetes 操作。以下为典型使用场景：

• 查看 Pod 列表：向 AI 提问 “列出 default 命名空间下的所有 Pod”
• 部署应用：提供 YAML 内容并说 “应用这个 Deployment”
• 诊断问题：使用内置指令 /k8s-diagnose nginx 自动排查含关键词 nginx 的 Pod 异常

✅ 默认使用当前 kubectl 上下文，支持自动加载 ~/.kube/config。高级认证方式（如环境变量、自定义路径）请参阅项目中的 ADVANCED_README.md。

启用只读模式（推荐用于生产环境）

防止误删资源，可启用非破坏性模式：

ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS=true npx mcp-server-kubernetes

此模式下仅允许查询、创建和更新操作，禁止删除类命令（如 kubectl delete）。