Kubernetes MCP Server

Kai - Kubernetes MCP 服务

用于通过 Claude Desktop、Cursor 和 Continue 等兼容 MCP 的客户端管理 Kubernetes 集群的模型上下文协议（MCP）服务。

概述

Kai 将 Kubernetes 操作作为 MCP 工具提供，让大模型客户端通过自然语言管理集群，包括工作负载、网络、配置、存储、RBAC、自定义资源和原始清单。

功能

核心工作负载

• Pods - 创建、列出、获取、删除 Pod 并流式传输日志
• Deployments - 创建、列出、描述和更新
• Jobs - 批处理工作负载管理（创建、获取、列出、删除）
• CronJobs - 定时批处理工作负载（创建、获取、列出、删除）

网络

• Services - 创建、获取、列出和删除
• Ingress - HTTP/HTTPS 路由、TLS 配置（创建、获取、列出、更新、删除）

配置

• ConfigMaps - 配置管理（创建、获取、列出、更新、删除）
• Secrets - 密钥管理（创建、获取、列出、更新、删除）
• Namespaces - 命名空间管理（创建、获取、列出、删除）

集群操作

• Context Management - 切换上下文、列出上下文、重命名和删除
• Nodes - 节点监控、隔离和排空（列出、获取、隔离、取消隔离、排空）
• Cluster Health - 集群状态和资源指标（集群健康状况、节点/Pod 指标）

存储

• Persistent Volumes - PV 管理（列出、获取、删除）和 PVC 管理（创建、列出、获取、删除）
• Storage Classes - 存储类操作（列出、获取）

安全

• RBAC - 角色、角色绑定、集群角色、集群角色绑定和服务账号（列出、获取）

实用工具

• Port Forwarding - 将端口转发到 Pod 和服务（启动、停止、列出会话）

高级功能

• Apply/Delete Manifests - 应用或删除原始 YAML/JSON，支持多文档及包括 CRD 在内的任意类型（apply_yaml、delete_yaml）
• Custom Resources - CRD 和自定义资源操作（列出/获取 CRD，列出/获取/删除自定义资源）
• Events - 事件列表与筛选（按命名空间、类型、涉及对象）
• API Discovery - API 资源探索（list_api_resources）

要求

默认情况下，服务会连接到当前 kubectl 上下文。请确保你可以访问已为 kubectl 配置的 Kubernetes 集群（例如 minikube、Rancher Desktop、kind、EKS、GKE、AKS）。

安装

go install github.com/basebandit/kai/cmd/kai@latest

容器镜像

Docker Hub 上提供了多架构镜像（linux/amd64、linux/arm64）：

docker pull cyclon/kai:v1.0.0
docker run --rm cyclon/kai:v1.0.0 -version

CLI 选项

kai [options]

Options:
  -kubeconfig string        Path to kubeconfig file (default "~/.kube/config")
  -context string           Name for the loaded context (default "local")
  -in-cluster               Use in-cluster config (when running inside a pod)
  -transport string         stdio (default), streamable-http, or sse-legacy
  -sse-addr string          HTTP listen address for streamable-http/sse-legacy (default ":8080")
  -tls-cert string          Path to TLS certificate (enables HTTPS)
  -tls-key string           Path to TLS private key (enables HTTPS)
  -request-timeout duration Timeout for Kubernetes API requests (default 30s)
  -metrics                  Expose Prometheus metrics at /metrics (default true)
  -log-format string        json (default) or text
  -log-level string         debug, info, warn, error (default "info")
  -version                  Show version information

默认情况下，日志以结构化 JSON 格式写入 stderr，便于解析：

{"time":"2024-01-15T10:30:00Z","level":"INFO","msg":"kubeconfig loaded","path":"/home/user/.kube/config","context":"local"}
{"time":"2024-01-15T10:30:00Z","level":"INFO","msg":"starting server","transport":"stdio"}

配置

Claude Desktop

编辑 Claude Desktop 配置：

# macOS
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Linux
code ~/.config/Claude/claude_desktop_config.json

添加服务配置：

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kai"
    }
  }
}

使用自定义 kubeconfig：

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kai",
      "args": ["-kubeconfig", "/path/to/custom/kubeconfig"]
    }
  }
}

Cursor

添加到 Cursor MCP 设置：

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/kai"
    }
  }
}

Continue

添加到 Continue 配置（~/.continue/config.json）：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "/path/to/kai"
        }
      }
    ]
  }
}

HTTP 模式（Web 客户端、远程使用）

对于非 stdio 客户端，请运行可流式传输的 HTTP 传输：

kai -transport=streamable-http -sse-addr=:8080

MCP 端点为 http://localhost:8080/mcp。健康探测端点为 /healthz 和 /readyz，Prometheus 指标端点为 /metrics。旧版 SSE 传输 （-transport=sse-legacy，端点 /sse）仍可使用，但已弃用。

自定义 Kubeconfig

默认情况下，Kai 使用 ~/.kube/config。你可以指定其他 kubeconfig：

kai -kubeconfig=/path/to/custom/kubeconfig -context=my-cluster

在 Kubernetes 集群内运行

在 Kubernetes 集群内部署 Kai 时，请使用 -in-cluster 标志，自动使用 Pod 的服务账号凭据：

kai -in-cluster -transport=streamable-http -sse-addr=:8080

推荐使用 kmcp（来自 kagent）在集群内运行 Kai。kmcp 会将 MCP 服务作为 MCPServer 资源进行管理：

apiVersion: kagent.dev/v1alpha1
kind: MCPServer
metadata:
  name: kai
spec:
  transportType: http
  httpTransport:
    targetPort: 8080
    path: /mcp
  deployment:
    image: cyclon/kai:v1.0.0
    port: 8080
    cmd: /kai
    args: ["-in-cluster", "-transport=streamable-http", "-sse-addr=:8080"]
    serviceAccountName: kai

kmcp 会为你创建 Deployment 和 Service。服务账号需要具备 Kai 所管理资源的 RBAC 权限——广泛的 get/list/watch 权限，以及在使用变更类工具时所需的 create/update/delete 权限。请参阅 kmcp 部署指南。

可运行示例：deploy/kagent/kai.example.yaml（仅用于测试——授予 cluster-admin 权限；实际使用时请缩小权限范围）。

使用示例

配置完成后，你可以使用自然语言与集群交互：

• “列出 default 命名空间中的所有 Pod”
• “使用 nginx:latest 镜像，创建一个名为 nginx、包含 3 个副本的 Deployment”
• “显示 Pod my-app 的日志”
• “删除名为 backend 的 Service”
• “创建一个每 5 分钟运行一次的 CronJob”
• “为 my-app 创建一个启用 TLS 的 Ingress”
• “将 Service nginx 的端口 8080 转发到 80”
• “应用此清单：<粘贴 YAML>”

贡献

欢迎贡献！更多信息请参阅我们的贡献指南。

许可证

本项目采用 MIT License 授权。

---