K8s MCP 服务器

K8s MCP 服务器是一个基于 fastapi-mcp 构建的、可通过网络访问的服务。它使 Claude 等大型语言模型 (LLM) 能够安全地运行 Kubernetes CLI 工具（kubectl, istioctl, helm, argocd）。它通过标准的模型控制协议（MCP）提供服务，并支持在每次请求中动态传入 kubeconfig，从而实现对多个 Kubernetes 集群的无缝管理。

核心特性

• 标准 MCP 实现: 使用 fastapi-mcp 将 FastAPI 端点自动暴露为 MCP 工具，无需手动实现协议。
• 动态多集群支持: 在每次 API 请求中直接以 Base64 编码的形式传入 kubeconfig 内容，无需预先配置或挂载文件。
• 独立的工具端点: 每个 CLI 工具（kubectl, helm 等）都有自己专用的 HTTP 端点，结构清晰。
• 独立服务: 可作为独立的 Docker 容器或在 Kubernetes 中运行。
• 自动 OpenAPI 文档: 继承 FastAPI 的优势，自动生成并提供交互式 API 文档（通过 /docs）。

工作原理

graph TD
    subgraph "客户端 (例如：LLM Agent, mcphost)"
        A["用户/LLM"]
    end
    
    subgraph "K8s MCP 服务器 (FastAPI 应用)"
        B["MCP 端点 (/mcp)"]
        C["工具端点 (/tools/kubectl)"]
        D["执行引擎"]
    end

    subgraph "目标环境"
        E["目标 Kubernetes 集群"]
    end

    A -->|"1. MCP 客户端连接到 /mcp"| B;
    B -->|"2. 发现可用工具 (kubectl, helm...)"| A;
    A -->|"3. 发起工具调用请求 (含 command 和 kubeconfig)"| C;
    C -->|"4. 调用执行引擎"| D;
    D -->|"5. 创建临时 kubeconfig 并执行命令"| E;
    E -->|"6. 返回结果"| D;
    D -->|"7. 返回 CommandResponse"| C;
    C -->|"8. 将结果通过 MCP 返回"| A;

Loading

快速入门

1. 运行 K8s MCP 服务器

使用 Docker 在本地快速启动服务器：

docker run -d --rm -p 9096:9096 --name mcp-server \
  ghcr.io/tadata-org/k8s-mcp-server:latest

服务器现在正在 http://localhost:9096 上运行。您可以访问 http://localhost:9096/docs 查看所有可用的工具和其 API 文档。

2. 在 MCP 客户端中配置

对于任何支持 MCP 的客户端（如 mcphost、Cursor、Claude Desktop 等），请添加以下配置：

{
  "mcpServers": {
    "kubernetes": {
      "url": "http://localhost:9096/mcp"
    }
  }
}

将 localhost 替换为 k8s-mcp-server 运行主机的 IP 地址（如果不在同一台机器上）。

3. 开始使用

启动您的 MCP 客户端后，它将自动发现 K8s MCP 服务器提供的工具。现在您可以开始发出指令了。

• "使用 kubectl 工具，执行命令 get pods -n default。"
• "帮我检查 prod 命名空间中 nginx-deployment 的状态。"

API 使用示例 (Curl)

您可以直接通过 curl 与服务器的工具端点交互。

1. 将您的 kubeconfig 内容进行 Base64 编码：

   # macOS
   KUBECONFIG_B64=$(cat ~/.kube/config | base64)
   
   # Linux
   KUBECONFIG_B64=$(cat ~/.kube/config | base64 -w 0)

2. 向 /tools/kubectl 端点发送请求（通过请求体传递kubeconfig）：

   curl -X POST http://localhost:9096/tools/kubectl \
     -H "Content-Type: application/json" \
     -d @- << EOF
   {
     "command": "get pods -n default",
     "kubeconfig": "$KUBECONFIG_B64"
   }
   EOF

3. 或者通过HTTP header传递kubeconfig：

   curl -X POST http://localhost:9096/tools/kubectl \
     -H "Content-Type: application/json" \
     -H "X-Kubeconfig: $KUBECONFIG_B64" \
     -d @- << EOF
   {
     "command": "get pods -n default"
   }
   EOF

   您将收到一个 JSON 响应，其中包含命令执行的结果。

功能特性

• 多种 Kubernetes 工具：kubectl、helm、istioctl 和 argocd。
• 云提供商原生支持：由于 kubeconfig 是动态传入的，因此原生支持任何符合标准的 Kubernetes 集群，包括 AWS EKS、Google GKE 和 Azure AKS。
• 安全性：以非 root 用户在容器中运行。
• 轻松配置：通过环境变量进行简单配置。

文档

• API 文档: 启动服务器后，请访问 /docs 路径以获取完整的交互式 API 文档。
• fastapi-mcp 文档: https://github.com/tadata-org/fastapi_mcp

贡献

我们欢迎社区的贡献！请随时提交问题和拉取请求。