MCP Server Kubernetes

MCP Server Kubernetes

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

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

安装与使用

前置条件

使用任何工具连接此 MCP 服务前，请确保满足以下条件：

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

你可以在终端中运行 kubectl get pods，确认能够连接集群且没有凭据问题。

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

Claude Code

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

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

这会自动在 Claude Code 的 MCP 设置中配置此服务。

Codex

使用内置命令将 MCP 服务添加到 Codex CLI：

codex mcp add kubernetes -- npx mcp-server-kubernetes

这会在 ~/.codex/config.toml 中全局注册此服务，并使其工具在所有 Codex 会话中可用。

Claude Desktop

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

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

通过 mcpb 使用 Claude Desktop Connector

MCP Server Kubernetes 也可作为 mcpb（原名 dxt）扩展使用。在 Claude Desktop 中，前往 Settings（Mac 上按 Cmd+,）-> Extensions -> Browse Extensions，然后在弹出的窗口中找到 mcp-server-kubernetes。安装后，它会通过命令行安装并使用 kubectl 和你的 kubeconfig。

如需手动安装，也可以前往最新的 Release 并下载 .mcpb。

VS Code

VS Code 内置了 MCP 支持。使用上方的一键安装按钮，或将服务添加到工作区中的 .vscode/mcp.json（也可以通过 MCP: Open User Configuration 添加到用户级 mcp.json）：

{
  "servers": {
    "kubernetes": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

Cursor

Cursor 通过其 AI 集成功能支持 MCP 服务。将服务添加到 ~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）：

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

该服务将自动连接到当前的 kubectl 上下文。你可以让 AI 助手列出 Pod 或创建测试部署，以验证连接。

Muse Code

Muse Code 从 ~/.config/muse/settings.json 的 mcp_servers 块读取 MCP 服务。文件必须包含 "schema_version": 1：

{
  "schema_version": 1,
  "mcp_servers": {
    "kubernetes": {
      "transport": "stdio",
      "command": "npx",
      "args": ["mcp-server-kubernetes"]
    }
  }
}

若要改用 Streamable HTTP 连接，请先以 HTTP 模式启动服务（默认在端口 3000 上提供 /mcp；参见 Streamable HTTP Transport）：

ENABLE_UNSAFE_STREAMABLE_HTTP_TRANSPORT=1 npx mcp-server-kubernetes

然后使用 streamable_http 传输方式将 Muse Code 指向该端点（headers 为可选项）：

{
  "schema_version": 1,
  "mcp_servers": {
    "kubernetes": {
      "transport": "streamable_http",
      "url": "http://localhost:3000/mcp",
      "mode": "optional"
    }
  }
}

"mode": "optional" 会在 HTTP 服务未运行时让 Muse Code 显示警告并继续启动，而不是中止启动。

编辑文件后，请启动新的 Muse Code 会话，然后运行 /mcp，确认 kubernetes 服务及其工具已连接。

使用 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 集群
• 用于管理资源的统一 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 操作
    • 安装、升级和卸载图表
    • 支持自定义值、仓库和版本
    • 基于模板安装（helm_template_apply），绕过身份验证问题
    • 基于模板卸载（helm_template_uninstall），绕过身份验证问题
  • Pod 清理操作
    • 清理处于以下状态的异常 Pod（cleanup_pods）：Evicted、ContainerStatusUnknown、Completed、Error、ImagePullBackOff、CrashLoopBackOff
  • 节点管理操作
    • 为维护和扩缩容操作封锁、排空和解除封锁节点（node_management）
• 故障排除提示词（k8s-diagnose）
  • 根据关键词和可选的命名空间，引导用户系统地排查 Kubernetes Pod 问题。
• 非破坏模式，仅允许读取集群以及创建或更新资源
• 为保障安全而屏蔽机密信息（屏蔽 kubectl get secrets 命令中的敏感数据，不影响日志）
• OpenTelemetry 可观测性（选择启用）
  • 为所有工具调用提供分布式追踪
  • 导出到 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 示例

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

# Enable telemetry
export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
export OTEL_TRACES_SAMPLER=always_on

# Run server
npx mcp-server-kubernetes

# View traces: http://localhost:16686

提示词

MCP Kubernetes 服务包含专用提示词，可协助执行常见的诊断操作。

/k8s-diagnose 提示词

此提示词为 Kubernetes Pod 提供系统化的故障排查流程。它接受用于识别相关 Pod 的 keyword，以及用于缩小搜索范围的可选 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
# 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。

高级功能

非破坏性模式

你可以在非破坏性模式下运行服务，该模式会禁用所有破坏性操作（删除 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、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 命令访问（可能包含破坏性操作）
• exec_in_pod：在 Pod 内执行任意命令（可读取 service-account 令牌并更改状态）

如需了解其他高级功能，请参阅 ADVANCED_README.md；有关 helm_install、helm_template_apply、节点管理和 Pod 清理的具体信息，请参阅 docs 文件夹。

架构

请参阅此 DeepWiki 链接，了解由 Devin 编写的更深入的架构概述。

本节介绍 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

请参阅此 DeepWiki 链接，了解 Devin 编写的更深入的架构概述。

发布新版本

前往 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}
}