K8s MCP Server

K8s MCP 服务

K8s MCP 服务是一个基于 Docker 的服务，实现了 Anthropic 的 Model Context Protocol（MCP），使 Claude 能够在安全的容器化环境中运行 Kubernetes CLI 工具（kubectl、istioctl、helm、argocd）。

演示：部署并排查 WordPress 故障

会话 1： 使用 k8s-mcp-server 和 Helm CLI 在 claude-demo 命名空间中部署 WordPress 应用，然后将 MariaDB StatefulSet 缩容至零，故意使其无法正常运行。

会话 2： 故障排查会话中，我们使用 k8s-mcp-server 通过 kubectl 命令诊断出现故障的 WordPress 网站，找出数据库缺失问题，并通过扩容 StatefulSet 和配置 ingress 访问来修复问题。

演示

工作原理

flowchart LR
    A[User] --> |Asks K8s question| B[Claude]
    B --> |Sends command via MCP| C[K8s MCP Server]
    C --> |Executes kubectl, helm, etc.| D[Kubernetes Cluster]
    D --> |Returns results| C
    C --> |Returns formatted results| B
    B --> |Analyzes & explains| A

Claude 可以帮助用户：

• 解释复杂的 Kubernetes 概念
• 在你的集群上运行命令
• 排查问题
• 提出优化建议
• 编写 Kubernetes 清单

使用 Claude Desktop 快速入门

不到 2 分钟，让 Claude 帮你管理 Kubernetes 集群：

1. 创建或更新 Claude Desktop 配置文件：

   • macOS：编辑 $HOME/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：编辑 %APPDATA%\Claude\claude_desktop_config.json
   • Linux：编辑 $HOME/.config/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "kubernetes": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-v",
           "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
           "ghcr.io/alexei-led/k8s-mcp-server:latest"
         ]
       }
     }
   }
   

2. 重启 Claude Desktop

   • 重启后，你会在输入框右下角看到工具图标（🔨）
   • 这表示 Claude 现在可以通过 MCP 服务访问 K8s 工具

3. 直接在 Claude Desktop 中开始使用 K8s 工具：

   • “我有哪些可用的 Kubernetes 上下文？”
   • “显示 default 命名空间中的所有 Pod”
   • “创建一个包含 3 个 nginx:1.21 副本的部署”
   • “说明我的命名空间 'prod' 中的 StatefulSet 'database' 有什么问题”
   • “使用 Helm 部署 bitnami/wordpress chart，并将服务类型设为 LoadBalancer”

注意：Claude Desktop 会自动通过 MCP 服务路由 K8s 命令，让你无需离开 Claude 界面，就能自然地讨论集群相关内容。

云服务提供商：对于 AWS EKS、GKE 或 Azure AKS，你需要进行额外配置。请参阅云服务提供商支持指南。

功能

• 多种 Kubernetes 工具：在一个容器中提供 kubectl、helm、istioctl 和 argocd
• 云服务提供商：原生支持 AWS EKS、Google GKE 和 Azure AKS
• 安全性：以非 root 用户身份运行，并严格验证命令
• 命令管道：支持 jq、grep 和 sed 等常见 Unix 工具
• 轻松配置：使用简单的环境变量进行自定义

传输协议

此服务支持三种传输协议，可通过 K8S_MCP_TRANSPORT 配置：

传输方式	描述	默认值
stdio	标准输入/输出（Claude Desktop 默认）	是
streamable-http	HTTP 传输（推荐用于远程／Web 客户端，MCP 规范 2025-11-25）	否
sse	服务器发送事件（已弃用，请改用 streamable-http）	否

使用 Streamable HTTP 传输的示例：

docker run --rm -p 8000:8000 \
  -v ~/.kube:/home/appuser/.kube:ro \
  -e K8S_MCP_TRANSPORT=streamable-http \
  ghcr.io/alexei-led/k8s-mcp-server:latest

注意：在 Docker 中使用 HTTP 传输运行时，服务会自动绑定到 0.0.0.0，以便正确映射端口。在 Docker 外部运行时，则会绑定到 127.0.0.1。

文档

• 入门指南 - 详细的设置说明
• 云服务提供商支持 - EKS、GKE 和 AKS 配置
• 支持的工具 - 所有包含的 CLI 工具的完整列表
• 环境变量 - 配置选项
• 安全功能 - 安全模式和自定义规则
• Claude 集成 - Claude Desktop 详细设置
• 架构 - 系统架构和组件
• 详细规范 - 完整的技术规范

使用示例

连接后，你可以用自然语言请求 Claude 帮助处理 Kubernetes 任务：

flowchart TB
    subgraph "Basic Commands"
        A1["Show me all pods in the default namespace"]
        A2["Get all services across all namespaces"]
        A3["Display the logs for the nginx pod"]
    end
    
    subgraph "Troubleshooting"
        B1["Why is my deployment not starting?"]
        B2["Describe the failing pod and explain the error"]
        B3["Check if my service is properly connected to the pods"]
    end
    
    subgraph "Deployments & Configuration"
        C1["Deploy the Nginx Helm chart"]
        C2["Create a deployment with 3 replicas of nginx:latest"]
        C3["Set up an ingress for my service"]
    end
    
    subgraph "Advanced Operations"
        D1["Check the status of my Istio service mesh"]
        D2["Set up a canary deployment with 20% traffic to v2"]
        D3["Create an ArgoCD application for my repo"]
    end

Claude 可以理解你的意图，并根据你的请求运行相应的 kubectl、helm、istioctl 或 argocd 命令。随后，它可以用简单易懂的语言解释输出结果，或帮你排查问题。

Claude Desktop 高级配置

配置 Claude Desktop，以优化 Kubernetes 工作流：

指定目标集群和命名空间

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-e", "K8S_CONTEXT=production-cluster",
        "-e", "K8S_NAMESPACE=my-application",
        "-e", "K8S_MCP_TIMEOUT=600",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

连接到 AWS EKS 集群

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-v", "/Users/YOUR_USER_NAME/.aws:/home/appuser/.aws:ro",
        "-e", "AWS_PROFILE=production",
        "-e", "AWS_REGION=us-west-2",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

连接到 Google GKE 集群

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-v", "/Users/YOUR_USER_NAME/.config/gcloud:/home/appuser/.config/gcloud:ro",
        "-e", "CLOUDSDK_CORE_PROJECT=my-gcp-project",
        "-e", "CLOUDSDK_COMPUTE_REGION=us-central1",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

连接到 Azure AKS 集群

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-v", "/Users/YOUR_USER_NAME/.azure:/home/appuser/.azure:ro",
        "-e", "AZURE_SUBSCRIPTION=my-subscription-id",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

宽松安全模式

{
  "mcpServers": {
    "kubernetes": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/Users/YOUR_USER_NAME/.kube:/home/appuser/.kube:ro",
        "-e", "K8S_MCP_SECURITY_MODE=permissive",
        "ghcr.io/alexei-led/k8s-mcp-server:latest"
      ]
    }
  }
}

有关详细的安全配置选项，请参阅安全文档。

许可证

本项目基于 MIT License 授权，详情请参阅 LICENSE 文件。