K8s MCP Server

A server for Kubernetes CLI tools like kubectl, istioctl, helm, and argocd, supporting multi-cluster management via dynamic kubeconfig.

本项目是基于alexei-led/k8s-mcp-server的优秀工作。在此向原作者表示衷心的感谢！

graph TD subgraph "客户端" A["用户 / LLM"] end subgraph "K8s MCP 服务器" B["MCP 端点 (/mcp)"] C["工具端点"] D["执行引擎"] end subgraph "目标环境" E["目标 Kubernetes 集群"] end A -->|"MCP 客户端连接到 /mcp"| B; B -->|"发现可用工具"| A; A -->|"发起工具调用请求"| C; C -->|"调用执行引擎"| D; D -->|"创建临时 kubeconfig 并执行命令"| E; E -->|"返回结果"| D; D -->|"返回 CommandResponse"| C; C -->|"将结果通过 MCP 返回"| A;

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

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

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

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

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

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

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

您可以使用Makefile中的quick-start命令在本地快速启动服务器：

这将构建 Docker 镜像并在本地运行容器，服务器将在http://localhost:9096上运行。

git clone https://github.com/apecloud/mcp-k8s.git cd mcp-k8s

python3 -m venv .venv source .venv/bin/activate

uvicorn src.k8s_mcp_server.app:app --host 0.0.0.0 --port 9096

- 将 Base64 编码的kubeconfig内容放在X-KubeconfigHeader 中。
- 这种方式可以为大语言模型节约 Token 消耗，因为kubeconfig不会作为请求体的一部分计入模型输入。

- 将 Base64 编码的kubeconfig内容作为 JSON 请求体中的kubeconfig字段值。

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

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

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

- 多种 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

Provides safe, read-only access to Kubernetes cluster resources for debugging and inspection.