kubernetes-mcp

Kubernetes MCP

English | 中文

一个使用 Go 构建、专注于 Kubernetes 的 Model Context Protocol（MCP）服务。 它将 Kubernetes 操作作为 MCP 工具提供，并支持 stdio、sse 和 streamable 传输方式。

为什么选择本项目

• 为 Kubernetes 操作提供统一的 MCP 接口
• 同时支持本地 kubeconfig 和集群内配置
• 提供多种传输方式，以适应不同的集成模式
• 通用资源 CRUD + 实用工具 + 提示词 + 指标
• 基于 slog 的日志记录，支持配置级别和格式

要求

• Go 1.24+
• 可访问 Kubernetes 集群
  • 通过 --kubeconfig，或
  • 通过集群内服务账号

快速开始

构建

git clone https://github.com/HSn0918/kubernetes-mcp.git
cd kubernetes-mcp
go build -o kubernetes-mcp ./cmd/kubernetes-mcp

运行（stdio）

./kubernetes-mcp server transport stdio --kubeconfig ~/.kube/config

运行（SSE）

./kubernetes-mcp server transport sse \
  --port 8080 \
  --health-port 8081 \
  --allow-origins "*" \
  --base-url "http://localhost:8080" \
  --kubeconfig ~/.kube/config

运行（StreamableHTTP）

./kubernetes-mcp server transport streamable \
  --port 8080 \
  --health-port 8081 \
  --allow-origins "*" \
  --kubeconfig ~/.kube/config

CLI 结构

kubernetes-mcp
├── server
│   └── transport
│       ├── stdio
│       ├── sse
│       └── streamable
└── version

配置标志

全局标志：

• --log-level（debug|info|warn|error，默认值为 info）
• --log-format（console|json，默认值为 console）
• --kubeconfig（可选）

网络传输标志（sse、streamable）：

• --port（默认值为 8080）
• --health-port（默认值为 8081）
• --allow-origins（默认值为 *）

仅 SSE 支持的标志：

• --base-url（默认值为 http://localhost:<port>）

传输端点

• StreamableHTTP MCP 端点：POST /mcp
• 健康检查端点（仅 SSE/Streamable）：
  • GET /healthz
  • GET /readyz

工具概览

1. 通用资源操作

对于每个 API 组前缀，服务都会提供：

• LIST_<PREFIX>_RESOURCES
• GET_<PREFIX>_RESOURCE
• DESCRIBE_<PREFIX>_RESOURCE
• CREATE_<PREFIX>_RESOURCE
• UPDATE_<PREFIX>_RESOURCE
• DELETE_<PREFIX>_RESOURCE

已注册的前缀：

• K8S

2. 核心/集群实用工具

• LIST_NAMESPACES
• LIST_NODES
• GET_POD_LOGS
• ANALYZE_POD_LOGS

3. 实用工具

• GET_CURRENT_TIME
• GET_CLUSTER_INFO
• GET_API_RESOURCES
• SEARCH_RESOURCES
• EXPLAIN_RESOURCE
• APPLY_MANIFEST
• VALIDATE_MANIFEST
• DIFF_MANIFEST
• GET_EVENTS

4. 提示词工具

• KUBERNETES_YAML_PROMPT
• KUBERNETES_QUERY_PROMPT
• TROUBLESHOOT_PODS_PROMPT
• TROUBLESHOOT_NODES_PROMPT
• TROUBLESHOOT_NETWORK_PROMPT

5. 指标工具

• GET_NODE_METRICS
• GET_POD_METRICS
• GET_RESOURCE_METRICS
• GET_TOP_CONSUMERS

架构（k8s 风格的组/版本）

cmd/kubernetes-mcp/
  main.go
  app/
pkg/
  client/kubernetes/
  config/
  handlers/
    apis/
      core/v1/
      apps/v1/
    base/
    tool/
    prompt/
    metrics/
  server/
  health/
  logger/

Docker

构建：

docker build -t kubernetes-mcp:latest .

使用明确指定的传输命令运行：

docker run --rm -it \
  -v ~/.kube:/root/.kube \
  kubernetes-mcp:latest \
  server transport stdio --kubeconfig /root/.kube/config

Kubernetes 部署

部署清单位于 /deploy/kubernetes。

make k8s-deploy
# or
make k8s-deploy-kustomize

开发

make build
make test

Justfile + 一键安装 Skill

此仓库包含一个项目用法 Skill，位于 skills/kubernetes-mcp-usage。

# list just tasks
just

# common dev tasks
just build
just test

# install the project skill into Codex
just skill-install

# overwrite existing install
just skill-install-force

Skill 安装目标位置： $CODEX_HOME/skills/kubernetes-mcp-usage（若未设置 CODEX_HOME，则为 ~/.codex/skills/kubernetes-mcp-usage）。

安装后，重启 Codex 以加载该 Skill。

注意事项

• 资源操作取决于集群 API 的可用性和 RBAC 权限。
• 对于位于 ingress/反向代理之后的网络传输方式，请为 SSE 正确设置 --base-url。