Kubectl MCP Tool

kubectl-mcp-server

通过与 AI 的自然语言对话，掌控整个 Kubernetes 基础设施。
像与 DevOps 专家交流一样，直接与集群对话。调试崩溃的 Pod、优化成本、部署应用、审计安全性和管理 Helm 图表，一切尽在自然语言交流之中。
属于 CNCF Landscape，与 Terraform 并列

---

安装

使用 npx 快速开始（推荐——无需安装）

# Run directly without installation - works instantly!
npx -y kubectl-mcp-server

# Or install globally for faster startup
npm install -g kubectl-mcp-server

或使用 pip 安装（Python）

pip install kubectl-mcp-server

# Or run it isolated with uv
uvx --from kubectl-mcp-server kubectl-mcp

---

📑 目录

• 可以做什么？
• 为什么选择 kubectl-mcp-server？
• 在线演示
• 安装
  • 使用 npx 快速开始
  • 使用 pip 安装
  • Docker
• 入门指南
• 使用 AI 助手快速设置
• 所有受支持的 AI 助手
• 完整功能集
• 使用 CLI
• 高级配置
• 无状态 MCP（2026-07-28）
• 企业版
• 安全性
• 集成与生态系统
• 集群内部署
• 多集群支持
• 架构
• Agent 技能
• 开发与测试
• 贡献
• 支持与社区

---

可以做什么？

只需用自然语言向 AI 助手提问：

💬 “为什么我的 Pod 一直崩溃？”

• 通过日志、事件和资源分析，即时诊断崩溃问题
• 找出根本原因并提供可执行的建议

💬 “部署一个包含 3 个副本的 Redis 集群”

• 按照最佳实践创建部署
• 配置服务、持久化存储和健康检查

💬 “告诉我哪些 Pod 正在浪费资源”

• 由 AI 驱动的成本优化分析
• 提供资源建议和潜在节省金额

💬 “哪些服务无法连接到数据库？”

• 通过 DNS 解析诊断网络连接问题
• 从 Ingress 到 Pod 追踪服务链路

💬 “审计所有命名空间的安全性”

• 分析 RBAC 权限
• 扫描 Secret 安全性和 Pod 安全策略

默认提供 26 个工具，每个工具集均包含 209 个工具 | 14 个工作流提示词 | 8 个资源 + 6 个资源模板 | 无状态 MCP 2026-07-28 | 兼容所有主流 AI 助手

为什么选择 kubectl-mcp-server？

• 🚀 告别频繁切换上下文 - 在 AI 助手对话中直接管理 Kubernetes
• 🧠 AI 驱动的诊断 - 获取智能故障排查，而非原始数据
• 💰 内置成本优化 - 识别资源浪费并获取可执行的节省建议
• 🔒 满足企业需求 - 支持按工具设置作用域的 OAuth 2.1 身份验证、只读模式、Secret 脱敏，以及故障时拒绝访问的网络绑定
• ⚡ 无需学习 - 使用自然语言，无需记忆 kubectl 命令
• 🌐 广泛兼容 - 适用于 Claude、Cursor、Windsurf、Copilot 和其他 15+ 款 AI 工具
• ☸️ 生产级品质 - 无状态 HTTP 可通过任意负载均衡器进行扩展，提供 Helm chart，516 项测试全部通过

从调试崩溃的 Pod 到优化集群成本，kubectl-mcp-server 都是你的 AI 驱动 DevOps 助手。

在线演示

Claude Desktop

Cursor AI

Windsurf

安装

使用 npx 快速开始（推荐 — 零安装）

# Run directly without installation - works instantly!
npx -y kubectl-mcp-server

# Or install globally for faster startup
npm install -g kubectl-mcp-server

或使用 pip 安装（Python）

pip install kubectl-mcp-server

# Or run it isolated with uv
uvx --from kubectl-mcp-server kubectl-mcp

从 GitHub Release 安装

# Install specific version directly from GitHub release (replace {VERSION} with desired version)
pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v{VERSION}/kubectl_mcp_server-{VERSION}-py3-none-any.whl

# Example: Install v2.0.0
pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v2.0.0/kubectl_mcp_server-2.0.0-py3-none-any.whl

# Or install latest from git
pip install git+https://github.com/rohitg00/kubectl-mcp-server.git

前置条件

• Python 3.10+ 或 uv（用于 pip/uvx 安装）
• Node.js 18+（用于 npx 安装）
• 已安装并配置 kubectl
• 可访问 Kubernetes 集群

Docker

# Pull from Docker Hub
docker pull rohitghumare64/kubectl-mcp-server:latest

# Or pull from GitHub Container Registry
docker pull ghcr.io/rohitg00/kubectl-mcp-server:latest

# Run with stdio transport (the image runs as UID 10001 with HOME=/home/mcp)
docker run -i --rm -v $HOME/.kube:/home/mcp/.kube:ro rohitghumare64/kubectl-mcp-server:latest

# Run stateless HTTP on localhost only. The container listens on 0.0.0.0, so it refuses
# to start without OAuth (MCP_AUTH_ENABLED) or an explicit MCP_ALLOW_UNAUTHENTICATED=true.
docker run --rm -p 127.0.0.1:8000:8000 -v $HOME/.kube:/home/mcp/.kube:ro \
  -e MCP_ALLOW_UNAUTHENTICATED=true \
  rohitghumare64/kubectl-mcp-server:latest --transport http

入门指南

1. 测试服务（可选）

在与 AI 助手集成之前，请先验证安装：

# Check if kubectl is configured
kubectl cluster-info

# Test the MCP server directly
kubectl-mcp-server info

# List all available tools
kubectl-mcp-server tools

# Try calling a tool
kubectl-mcp-server call kubectl_get '{"resource_type": "pods", "namespace": "kube-system"}'

2. 连接到 AI 助手

选择你喜欢的 AI 助手并添加配置：

使用 AI 助手快速设置

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

Cursor AI

添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

Windsurf

添加到 ~/.config/windsurf/mcp.json：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

使用 Python 而非 npx

{
  "mcpServers": {
    "kubernetes": {
      "command": "python",
      "args": ["-m", "kubectl_mcp_tool.mcp_server"],
      "env": {
        "KUBECONFIG": "/path/to/.kube/config"
      }
    }
  }
}

更多集成：GitHub Copilot、Goose、Gemini CLI、Roo Code 和其他 15+ 个客户端 —> 请参阅下方的完整配置指南。

3. 重启 AI 助手

添加配置后，请重启 AI 助手 （GitHub Copilot、Claude Code、Claude Desktop、Cursor 等），以加载 MCP 服务。

4. 尝试这些命令

开始与 AI 助手对话，并尝试以下内容：

故障排除：

"Show me all pods in the kube-system namespace"
"Why is the nginx-deployment pod crashing?"
"Diagnose network connectivity issues in the default namespace"

部署：

"Create a deployment for nginx with 3 replicas"
"Scale my frontend deployment to 5 replicas"
"Roll back the api-server deployment to the previous version"

成本与优化：

"Which pods are using the most resources?"
"Show me idle resources that are wasting money"
"Analyze cost optimization opportunities in the production namespace"

安全：

"Audit RBAC permissions in all namespaces"
"Check for insecure secrets and configurations"
"Show me pods running with privileged access"

Helm：

"List all Helm releases in the cluster"
"Install Redis from the Bitnami chart repository"
"Show me the values for my nginx-ingress Helm release"

多集群：

"List all available Kubernetes contexts"
"Switch to the production cluster context"
"Show me cluster information and version"

MCP 客户端兼容性

与所有兼容 MCP 的 AI 助手无缝协作：

客户端	状态	客户端	状态
Claude Desktop	✅ 原生支持	Claude Code	✅ 原生支持
Cursor	✅ 原生支持	Windsurf	✅ 原生支持
GitHub Copilot	✅ 原生支持	OpenAI Codex	✅ 原生支持
Gemini CLI	✅ 原生支持	Goose	✅ 原生支持
Roo Code	✅ 原生支持	Kilo Code	✅ 原生支持
Amp	✅ 原生支持	Trae	✅ 原生支持
OpenCode	✅ 原生支持	Kiro CLI	✅ 原生支持
Antigravity	✅ 原生支持	Clawdbot	✅ 原生支持
Droid (Factory)	✅ 原生支持	任意 MCP 客户端	✅ 兼容

所有受支持的 AI 助手

Claude Code

添加到 ~/.config/claude-code/mcp.json：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

GitHub Copilot（VS Code）

添加到 VS Code settings.json：

{
  "mcp": {
    "servers": {
      "kubernetes": {
        "command": "npx",
        "args": ["-y", "kubectl-mcp-server"]
      }
    }
  }
}

Goose

添加到 ~/.config/goose/config.yaml：

extensions:
  kubernetes:
    command: npx
    args:
      - -y
      - kubectl-mcp-server

Gemini CLI

添加到 ~/.gemini/settings.json：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

Roo Code / Kilo Code

添加到 ~/.config/roo-code/mcp.json 或 ~/.config/kilo-code/mcp.json：

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubectl-mcp-server"]
    }
  }
}

完整功能集

工具集

每个工具定义都会在每次请求中占用上下文；随着列表变长，模型选择工具的可靠性也会降低。因此，服务默认仅注册 core 和 helm 工具集（26 个工具）。kubectl_get、kubectl_describe、kubectl_logs、kubectl_apply 等工具适用于所有资源类型，包括自定义资源，因此默认工具集足以满足大多数日常工作需求。其他工具均为可选项；未启用的工具集中的工具不会注册，因此无法调用。

kubectl-mcp-server                                    # core + helm
kubectl-mcp-server --toolsets default,diagnostics,certs
kubectl-mcp-server --toolsets all                     # all 209 tools
MCP_TOOLSETS=default,gitops kubectl-mcp-server        # same, via environment

detect_ecosystem 会报告已安装的运维工具，以及涵盖它们的工具集。启用多个工具集且客户端无法自行搜索工具时，请添加 --tool-search（MCP_TOOL_SEARCH=true）：此时服务只会列出默认工具以及 search_tools 和 call_tool，其余工具会按需发现。只读模式、作用域和脱敏规则仍适用于每次发现的调用。

对于某个生态系统中的深度工作，通常使用由该项目维护的 MCP 服务会比启用可选工具集更合适：

生态系统	MCP 服务
Argo CD	argoproj-labs/mcp-for-argocd
Flux	Flux Operator MCP 服务
Kyverno	nirmata/kyverno-mcp
工具集	默认启用
---------	---------
core	是
helm	是
helm_dev
ops
diagnostics
security
cost
multicluster
crds
gitops
certs
policy
backup
keda
cilium
rollouts
capi
kubevirt
istio
kind
vind

MCP 资源

将 Kubernetes 数据作为可浏览资源进行访问：

资源 URI	描述
kubeconfig://contexts	列出所有可用的 kubectl 上下文
kubeconfig://current-context	获取当前活动上下文
namespace://current	获取当前命名空间
namespace://list	列出所有命名空间
cluster://info	获取集群信息
cluster://nodes	获取详细的节点信息
cluster://version	获取 Kubernetes 版本
cluster://api-resources	列出可用的 API 资源
manifest://deployments/{ns}/{name}	获取 Deployment YAML
manifest://services/{ns}/{name}	获取 Service YAML
manifest://pods/{ns}/{name}	获取 Pod YAML
manifest://configmaps/{ns}/{name}	获取 ConfigMap YAML
manifest://secrets/{ns}/{name}	获取 Secret YAML（数据已遮蔽）
manifest://ingresses/{ns}/{name}	获取 Ingress YAML

MCP 提示词

针对常见 Kubernetes 操作预构建的工作流提示词：

提示词	描述
troubleshoot_workload	Pod/Deployment 综合故障排查指南
deploy_application	逐步部署工作流
security_audit	安全扫描和 RBAC 分析工作流
cost_optimization	资源优化和成本分析工作流
disaster_recovery	备份和恢复规划工作流
debug_networking	服务和连接性的网络调试
scale_application	包含 HPA/VPA 最佳实践的扩缩容指南
upgrade_cluster	Kubernetes 集群升级规划
cluster_health_check	集群范围的健康状况检查
debug_workload	针对指定工作负载的逐步调试
resource_usage	资源消耗和规格调整检查
security_posture	命名空间或集群安全态势检查
deployment_checklist	应用部署前检查清单
incident_response	按事件类型分类的事件处理手册

在 ~/.config/kubectl-mcp/prompts.toml 中添加自定义提示词；同名提示词会覆盖内置提示词。

主要功能

• 🤖 26 个默认工具，209 个可选工具集 - 默认提供通用 kubectl 和 Helm，按需启用生态工具集
• 🎯 14 个工作流提示词 - 针对常见操作预构建的工作流
• 📊 8 个资源 + 6 个模板 - 可浏览的 Kubernetes 数据
• 🔄 可选生态工具集 - GitOps、cert-manager、policy、Velero、KEDA、Cilium、Rollouts、CAPI、KubeVirt、Istio、kind、vCluster
• ⚡ 无状态 MCP 2026-07-28 - 支持 stdio 和 Streamable HTTP，自动协商兼容旧版客户端
• 🔐 安全优先 - 只读模式、每次调用确认、Secret 内容遮蔽、防止标志注入
• 🏥 高级诊断 - AI 驱动的故障排查和成本优化
• ☸️ 多集群 - 每个工具都可通过 context 参数指定任意集群
• 🎡 完整 Helm v3 - 完整的 Chart 生命周期管理
• 🔧 强大的命令行工具 - 便于 Shell 使用的工具发现和直接调用
• 🐳 云原生 - 使用 kMCP 或 kagent 在集群内部署

使用命令行工具

内置命令行工具让你无需 AI 助手即可探索和测试工具：

# List all tools with descriptions
kubectl-mcp-server tools -d

# Search for pod-related tools
kubectl-mcp-server grep "*pod*"

# Show specific tool schema
kubectl-mcp-server tools kubectl_get

# Call a tool directly
kubectl-mcp-server call kubectl_get '{"resource_type": "pods", "namespace": "kube-system"}'

# Pipe JSON from stdin
echo '{"resource_type": "pods"}' | kubectl-mcp-server call kubectl_get

# Check dependencies
kubectl-mcp-server doctor

# Show/switch Kubernetes context
kubectl-mcp-server context
kubectl-mcp-server context minikube

# List resources and prompts
kubectl-mcp-server resources
kubectl-mcp-server prompts

# Show server info
kubectl-mcp-server info

命令行工具功能

• 结构化错误：提供可执行的错误消息和建议
• 彩色输出：提供易读输出，并支持用于脚本的 JSON 模式（--json）
• NO_COLOR 支持：遵循 NO_COLOR 环境变量
• 标准输入支持：将 JSON 参数通过管道传递给命令

高级配置

传输模式

# stdio (default) - Claude Desktop, Cursor, Windsurf, Claude Code
kubectl-mcp-server

# Streamable HTTP, stateless, at http://127.0.0.1:8000/mcp
kubectl-mcp-server --transport http --port 8000

# SSE - deprecated by the MCP spec (SEP-2596), session-bound; kept for old clients
kubectl-mcp-server --transport sse --port 8000

服务选项（每个标志也会读取对应的环境变量）：

标志	环境变量	默认值	描述
--transport	MCP_SERVER_TRANSPORT	stdio	stdio、http / streamable-http、sse
--host	MCP_SERVER_HOST	127.0.0.1	网络传输的绑定地址
--port	MCP_SERVER_PORT	8000	网络传输的端口
--allow-unauthenticated	MCP_ALLOW_UNAUTHENTICATED	off	允许在非环回地址上绑定而不使用 OAuth
--toolsets	MCP_TOOLSETS	default	要注册的工具集（default、all 或名称；参见工具集）
--tool-search	MCP_TOOL_SEARCH	off	列出默认工具及 search_tools/call_tool；按需发现其余工具
--read-only	MCP_SAFETY_MODE=read-only	off	隐藏并阻止所有会更改状态的工具
--disable-destructive	MCP_SAFETY_MODE=disable-destructive	off	允许创建/更新，阻止删除
--confirm-destructive	MCP_SAFETY_MODE=confirm	off	每次执行破坏性调用前询问用户
--stateless	MCP_STATELESS_MODE	off	不缓存 Kubernetes API 客户端
--watch-kubeconfig	MCP_KUBECONFIG_WATCH	off	kubeconfig 发生变化时重新加载
--config			TOML 配置文件

环境变量

核心设置：

变量	描述	默认值
KUBECONFIG	kubeconfig 文件的路径	~/.kube/config
MCP_DEBUG	启用详细日志记录	false
MCP_LOG_FILE	日志文件路径	None（stdout）

身份验证（企业版）：

变量	描述	默认值
MCP_AUTH_ENABLED	启用 OAuth 2.1 身份验证	false
MCP_AUTH_ISSUER	OAuth 2.0 授权服务器 URL	-
MCP_AUTH_JWKS_URI	JWKS 端点 URL	自动推导
MCP_AUTH_AUDIENCE	预期的令牌受众	kubectl-mcp-server
MCP_AUTH_REQUIRED_SCOPES	每个令牌都必须携带的作用域	mcp:tools
MCP_AUTH_RESOURCE_URL	RFC 9728 元数据中公布的公共 URL	-

安全与扩展：

变量	描述	默认值
MCP_SAFETY_MODE	read-only、disable-destructive、confirm、normal（无效值会导致启动失败）	normal
MCP_MASK_SECRETS	对工具输出中的 Secret 值、Bearer 令牌和 JWT 进行脱敏	true
MCP_ALLOWED_HOSTS / MCP_ALLOWED_ORIGINS	用逗号分隔的 HTTP Host / Origin 允许列表	环回地址
MCP_REQUEST_STATE_KEY	>= 32 字节的密钥，由多个副本共享，以便确认流程可由任意副本处理	每个进程独立

企业版：OAuth 2.1 身份验证

使用 OAuth 2.1 身份验证（RFC 9728）保护 MCP 服务。

export MCP_AUTH_ENABLED=true
export MCP_AUTH_ISSUER=https://your-idp.example.com
export MCP_AUTH_AUDIENCE=kubectl-mcp-server
kubectl-mcp-server --transport http --port 8000

支持的身份提供商：Okta、Auth0、Keycloak、Microsoft Entra ID、Google OAuth，以及任何符合 OIDC 的提供商。

作用域：携带 mcp:tools 或 mcp:admin 的令牌可以调用所有工具。将 MCP_AUTH_REQUIRED_SCOPES=mcp:read 设置为颁发权限更窄的令牌：只读工具需要 mcp:read，会更改状态的工具需要 mcp:write。

安全

• 网络暴露默认拒绝。 HTTP 默认绑定到 127.0.0.1。绑定到其他任何地址都需要 OAuth 或 --allow-unauthenticated；Helm chart 在未提供其中任一选项时会拒绝渲染。
• 只读模式会隐藏写入工具。 使用 --read-only（或 MCP_SAFETY_MODE=read-only）时，所有 readOnlyHint 为 false 的工具都会从 tools/list 中移除，调用时也会被拒绝。
• 无状态协议支持确认操作。 --confirm-destructive 会向 2026-07-28 客户端返回 MRTR InputRequiredResult，并对较旧客户端回退为 elicitation。批准与确切操作绑定。
• 密钥会被脱敏。 每个工具结果中的 Secret data、stringData、last-applied-configuration 注解、不记名令牌和 JWT 都会替换为 [REDACTED]。
• 禁止标志注入。 以 - 开头的标识符参数（name、namespace、chart、context、标签键等）会在运行任何 CLI 之前被拒绝，因此 name="--server=https://attacker" 永远不会传递给 kubectl 或 helm。kubectl_generic 只会运行只读动词，并会阻止凭据、连接和原始输出标志。
• 不使用 Shell。 所有子进程调用都使用参数列表；不会通过 sh -c 运行任何内容。CVE-2025-69902（kubectl-mcp-tool <= 1.1.1 中的 Shell 注入）已在 1.2.0 中修复；请升级所有更旧的版本。

请私下报告漏洞；参见 SECURITY.md。

无状态 MCP（2026-07-28）

服务遵循 2026-07-28 规范：无需 initialize 握手，不使用 Mcp-Session-Id，通过 server/discover 获取功能，并使用逐请求 _meta。对于 2025 年版本的客户端，同一进程会通过 stdio 和 HTTP 自动协商。

由于请求之间互不依赖，HTTP 副本可在轮询负载均衡器后扩展，无需粘性会话或共享存储。如果使用 --confirm-destructive，请在每个副本上将 MCP_REQUEST_STATE_KEY 设为相同值。

curl -s http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' -H 'Mcp-Method: server/discover' \
  -d '{"jsonrpc":"2.0","id":1,"method":"server/discover","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientCapabilities":{}}}}'

集成与生态系统

Docker MCP Toolkit

可与 Docker MCP Toolkit 配合使用：

docker mcp server add kubectl-mcp-server mcp/kubectl-mcp-server:latest
docker mcp server configure kubectl-mcp-server --volume "$HOME/.kube:/home/mcp/.kube:ro"
docker mcp server enable kubectl-mcp-server
docker mcp client connect claude

agentregistry

从集中式 agentregistry 安装：

# Install arctl CLI
curl -fsSL https://raw.githubusercontent.com/agentregistry-dev/agentregistry/main/scripts/install.sh | bash

# Install kubectl-mcp-server
arctl mcp install io.github.rohitg00/kubectl-mcp-server

可通过以下方式使用：PyPI（uvx）、npm（npx）、OCI（docker.io/rohitghumare64/kubectl-mcp-server）

agentgateway

通过 agentgateway 路由到多个 MCP 服务：

# Start stateless Streamable HTTP
kubectl-mcp-server --transport http --port 8000

# Configure gateway
cat > gateway.yaml <<EOF
binds:
- port: 3000
  listeners:
  - routes:
    - backends:
      - mcp:
          targets:
          - name: kubectl-mcp-server
            mcp:
              host: http://localhost:8000/mcp
EOF

# Start gateway
agentgateway --config gateway.yaml

将客户端连接到 http://localhost:3000/mcp。

集群内部署

选项 1：kMCP（推荐）

使用 kMCP 部署——这是 MCP 服务的控制平面：

# Install kMCP
curl -fsSL https://raw.githubusercontent.com/kagent-dev/kmcp/refs/heads/main/scripts/get-kmcp.sh | bash
kmcp install

# Deploy kubectl-mcp-server (easiest)
kmcp deploy package --deployment-name kubectl-mcp-server \
   --manager npx --args kubectl-mcp-server

# Or with Docker image
kmcp deploy --file deploy/kmcp/kmcp.yaml --image rohitghumare64/kubectl-mcp-server:latest

详情请参阅 kMCP 快速入门。

选项 2：标准 Kubernetes

使用 kubectl/kustomize 部署：

# Using kustomize (recommended)
kubectl apply -k deploy/kubernetes/

# Or individual manifests
kubectl apply -f deploy/kubernetes/namespace.yaml
kubectl apply -f deploy/kubernetes/rbac.yaml
kubectl apply -f deploy/kubernetes/deployment.yaml
kubectl apply -f deploy/kubernetes/service.yaml

# Access via port-forward
kubectl port-forward -n kubectl-mcp svc/kubectl-mcp-server 8000:8000

所有清单和配置选项请参阅 deploy/ 目录。

选项 3：kagent（AI Agent 框架）

与 kagent 集成——这是一个 CNCF Kubernetes 原生 AI Agent 框架：

# Install kagent
brew install kagent
kagent install --profile demo

# Register as ToolServer
kubectl apply -f deploy/kagent/toolserver-stdio.yaml

# Open dashboard
kagent dashboard

现在，你的 AI Agent 可以使用该服务已启用的工具集。请参阅 kagent 快速入门。

架构

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   AI Assistant  │────▶│   MCP Server     │────▶│  Kubernetes API │
│ (Claude/Cursor) │◀────│ (kubectl-mcp)    │◀────│    (kubectl)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘

MCP 服务实现了 Model Context Protocol，将自然语言请求转换为 kubectl 操作。

模块化结构

kubectl_mcp_tool/
├── mcp_server.py          # Main server (FastMCP, transports)
├── middleware.py          # Safety mode, flag-injection guard, scopes, redaction, metrics
├── toolsets.py            # Toolset registry, server instructions
├── tools/                  # MCP tools, grouped into toolsets
│   ├── kubectl.py         # Generic get/logs/top/scale for every kind, detect_ecosystem
│   ├── pods.py            # Pod exec & diagnostics
│   ├── cluster.py         # Context/cluster management
│   ├── networking.py      # Network and DNS diagnostics
│   ├── security.py        # RBAC, pod security, secret hygiene audits
│   ├── helm.py            # Complete Helm v3 operations
│   ├── operations.py      # kubectl apply/patch/describe/etc
│   ├── diagnostics.py     # Metrics, namespace comparison
│   ├── cost.py            # Resource optimization & cost analysis
│   ├── gitops.py          # GitOps (Flux/ArgoCD)
│   ├── certs.py           # Cert-Manager
│   ├── policy.py          # Policy (Kyverno/Gatekeeper)
│   ├── backup.py          # Backup (Velero)
│   ├── keda.py            # KEDA autoscaling
│   ├── cilium.py          # Cilium/Hubble network observability
│   ├── rollouts.py        # Argo Rollouts/Flagger
│   ├── capi.py            # Cluster API
│   ├── kubevirt.py        # KubeVirt VMs
│   ├── kiali.py           # Istio/Kiali service mesh
│   ├── vind.py            # vCluster (virtual clusters)
│   ├── kind.py            # kind local clusters
│   └── custom_resources.py # CRD discovery
├── resources/              # 8 MCP Resources for data exposure
├── prompts/                # 14 MCP Prompts for workflows
└── cli/                    # CLI interface

Agent Skills（面向 AI 编码 Agent 的 25 项技能）

使用 kubernetes-skills/ 中的技能，为你的 AI 编码 Agent 扩展 Kubernetes 专业知识。技能提供专门知识和工作流，供 Agent 按需加载；每项技能都会列出所需的工具集。

快速安装

# Any agent (Claude Code, Codex, Cursor, OpenCode, Gemini CLI, ...) via the skills CLI
npx skills add rohitg00/kubectl-mcp-server

# A single skill for a single agent
npx skills add rohitg00/kubectl-mcp-server --skill k8s-helm --agent claude-code

# OpenClaw, from ClawHub (synced from this repo on every merge)
openclaw skills install @rohitg00/k8s-helm

# Or copy into Claude Code directly
cp -r kubernetes-skills/claude/* ~/.claude/skills/

可在 ClawHub 浏览这些技能，或使用 npx skills add rohitg00/kubectl-mcp-server --list 列出它们。

可用技能（25）

类别	技能
核心资源	k8s-core、k8s-networking、k8s-storage
工作负载	k8s-deploy、k8s-operations、k8s-helm
可观测性	k8s-diagnostics、k8s-troubleshoot、k8s-incident
安全	k8s-security、k8s-policy、k8s-certs
GitOps	k8s-gitops、k8s-rollouts
扩缩容	k8s-autoscaling、k8s-cost、k8s-backup
多集群	k8s-multicluster、k8s-capi、k8s-kubevirt
开发	k8s-vind、k8s-kind
网络	k8s-service-mesh、k8s-cilium
工具	k8s-cli

转换为其他 Agent

使用 SkillKit，将技能转换为你偏好的 AI Agent 格式：

npm install -g skillkit

# Convert to Cursor format
skillkit translate kubernetes-skills/claude --to cursor --output .cursor/rules/

# Convert to Codex format
skillkit translate kubernetes-skills/claude --to codex --output ./

支持的 Agent： Claude、Cursor、Codex、Gemini CLI、GitHub Copilot、Goose、Windsurf、Roo、Amp 等。

完整文档请参阅 kubernetes-skills/README.md。

多集群支持

通过自然语言无缝管理多个 Kubernetes 集群。每个工具都支持可选的 context 参数，可指定任意集群，无需切换上下文。

Context 参数（v1.15.0）

大多数基于 kubectl 的工具都接受可选的 context 参数，用于指定目标集群。 注意：vCluster（vind）和 kind 工具通过本地 CLI 运行，不接受 context 参数。

与 AI 助手交谈：

"List pods in the production cluster"
"Get deployments from staging context"
"Show logs from the api-pod in the dev cluster"
"Compare namespaces between production and staging clusters"

使用 context 直接调用工具：

# Target a specific cluster context
kubectl-mcp-server call kubectl_get '{"resource_type": "pods", "namespace": "default", "context": "production"}'

# Get deployments from staging
kubectl-mcp-server call kubectl_get '{"resource_type": "deployments", "namespace": "app", "context": "staging"}'

# Install Helm chart to production cluster
kubectl-mcp-server call install_helm_chart '{"name": "redis", "chart": "bitnami/redis", "namespace": "cache", "context": "production"}'

# Compare resources across clusters
kubectl-mcp-server call compare_namespaces '{"namespace1": "prod-ns", "namespace2": "staging-ns", "context": "production"}'

Context 管理

与 AI 助手交谈：

"List all available Kubernetes contexts"
"Switch to the production cluster"
"Show me details about the staging context"
"What's the current cluster I'm connected to?"

或直接使用 CLI：

kubectl-mcp-server context                    # Show current context
kubectl-mcp-server context production         # Switch context
kubectl-mcp-server call list_contexts         # List all contexts via MCP

工作原理

• 如果省略 context，工具将使用当前的 kubectl 上下文
• 如果指定 context，工具将直接以该集群为目标
• 响应中会包含 "context": "production" 或 "context": "current"，以便清晰识别
• 适用于所有 kubeconfig 配置，并遵循 KUBECONFIG 环境变量
• 跨集群操作无需切换上下文

开发与测试

搭建开发环境

# Clone the repository
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt

运行测试

# Run all tests
pytest tests/ -v

# Run specific test file
pytest tests/test_tools.py -v

# Run with coverage
pytest tests/ --cov=kubectl_mcp_tool --cov-report=html

# Run only unit tests
pytest tests/ -v -m unit

测试结构

tests/
├── __init__.py          # Test package
├── conftest.py          # Shared fixtures and mocks
├── test_tools.py        # Unit tests for all MCP tools
├── test_stateless_security.py # Both protocol eras, confirmation, redaction, injection guard
├── test_resources.py    # Tests for 8 MCP Resources
├── test_prompts.py      # Tests for 8 MCP Prompts
└── test_server.py       # Server initialization tests

555 项测试涵盖： 工具注册、资源公开、提示词生成、端到端测试两个 MCP 协议时代、安全模式、确认轮次、Secret 脱敏、标志注入、网络暴露、CLI 命令以及生态工具。

代码质量

# Format code
black kubectl_mcp_tool tests

# Sort imports
isort kubectl_mcp_tool tests

# Lint
flake8 kubectl_mcp_tool tests

# Type checking
mypy kubectl_mcp_tool

贡献

我们 ❤️ 欢迎贡献！无论是错误报告、功能请求、文档改进还是代码贡献，都欢迎参与。

贡献方式：

• 🐛 通过 GitHub Issues 报告错误
• 💡 提出功能或改进建议
• 📝 改进文档
• 🔧 提交拉取请求
• ⭐ 如果你觉得这个项目有用，请为它点星！

开发环境搭建： 请参阅上文的开发与测试部分。

提交 PR 前：

1. 运行测试：pytest tests/ -v
2. 格式化代码：black kubectl_mcp_tool tests
3. 检查代码规范：flake8 kubectl_mcp_tool tests

支持与社区

• 📖 文档
• 💬 GitHub 讨论区
• 🐛 问题跟踪
• 🎯 功能请求
• 🌟 agentregistry 主页

许可证

MIT 许可证 - 详情请参阅 LICENSE。

链接与资源

软件包仓库：

• 🐍 PyPI 软件包
• 📦 npm 软件包
• 🐳 Docker Hub

项目：

• 🔧 GitHub 仓库
• 🐛 问题跟踪器
• 📋 更新日志

生态系统：

• 📚 Model Context Protocol
• ☸️ Kubernetes 文档

---

为 Kubernetes 和 AI 社区倾心打造 ❤️

如果 kubectl-mcp-server 让你的 DevOps 工作更轻松，请在 GitHub 上为它点个 ⭐！