kubectl-mcp-server

通过与 AI 的自然语言对话，掌控您的整个 Kubernetes 基础设施。
像与 DevOps 专家交谈一样与您的集群互动。无需复杂操作，即可调试崩溃的 Pod、优化成本、部署应用、审计安全、管理 Helm 图表以及可视化仪表板——所有这些都可通过自然语言完成。

---

安装

使用 npx 快速入门（推荐——零安装）

# 无需安装即可直接运行，即刻生效！
npx -y kubectl-mcp-server

# 或者全局安装以加快启动速度
npm install -g kubectl-mcp-server

或使用 pip 安装（Python）

# 标准安装
pip install kubectl-mcp-server

# 推荐安装带交互式 UI 仪表盘的版本
pip install kubectl-mcp-server[ui]

---

📑 目录

• 你能做什么？
• 为什么选择 kubectl-mcp-server？
• 现场演示
• 安装
  • 使用 npx 快速入门（推荐——零安装）
  • 使用 pip 安装（Python）
  • Docker
• 开始使用
• 与你的 AI 助手快速设置
• 所有支持的 AI 助手
• 完整功能集
• 使用 CLI
• 高级配置
• 可选功能
  • 交互式仪表盘
  • 浏览器自动化
• 企业级
• 集成与生态系统
• 集群内部署
• 多集群支持
• 架构
• 代理技能
• 开发与测试
• 贡献代码
• 支持与社区

---

你能做什么？

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

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

• 即时诊断崩溃原因，提供日志、事件和资源分析
• 找出根本原因并给出可操作的建议

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

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

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

• 基于 AI 的成本优化分析
• 提供节省潜力及资源优化建议

💬 “哪些服务无法访问数据库？”

• 网络连通性诊断，包括 DNS 解析
• 从入口到 Pod 的服务链追踪

💬 “对所有命名空间进行安全审计”

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

💬 “展示集群仪表板”

• 交互式 HTML 仪表盘，实时显示指标
• 可视化事件和资源使用的时间线

253 种强大工具 | 8 个工作流提示 | 8 种数据资源 | 兼容所有主流 AI 助手

为什么选择 kubectl-mcp-server？

• 🚀 停止上下文切换 —— 直接从 AI 助手对话中管理 Kubernetes
• 🧠 AI 驱动的诊断 —— 提供智能故障排除，而非单纯的数据罗列
• 💰 内置成本优化 —— 发现资源浪费并给出可操作的节约建议
• 🔒 企业级安全 —— 支持 OAuth 2.1 认证、RBAC 验证、非破坏性模式和 Secret 掩码
• ⚡ 无学习曲线 —— 使用自然语言代替记忆复杂的 kubectl 命令
• 🌐 通用兼容性 —— 适用于 Claude、Cursor、Windsurf、Copilot 等 15+ 种 AI 工具
• 📊 可视化洞察 —— 提供交互式仪表盘和针对 Web 工具的浏览器自动化功能
• ☸️ 生产级可靠性 —— 可在集群内部署，经过 216 次测试验证，持续维护更新

无论是调试崩溃的 Pod 还是优化集群成本，kubectl-mcp-server 都是您值得信赖的 AI 驱动的 DevOps 伙伴。

现场演示

Claude Desktop

Cursor AI

Windsurf

安装

使用 npx 快速入门（推荐——零安装）

# 无需安装即可直接运行，即刻生效！
npx -y kubectl-mcp-server

# 或者全局安装以加快启动速度
npm install -g kubectl-mcp-server

或使用 pip 安装（Python）

# 标准安装
pip install kubectl-mcp-server

# 推荐安装带交互式 UI 仪表盘的版本
pip install kubectl-mcp-server[ui]

从 GitHub 发布版本安装

# 直接从 GitHub 发布版本安装特定版本（将 {VERSION} 替换为所需版本）
pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v{VERSION}/kubectl_mcp_server-{VERSION}-py3-none-any.whl

# 示例：安装 v1.19.0
pip install https://github.com/rohitg00/kubectl-mcp-server/releases/download/v1.19.0/kubectl_mcp_server-1.19.0-py3-none-any.whl

# 或者从 Git 仓库安装最新版本
pip install git+https://github.com/rohitg00/kubectl-mcp-server.git

先决条件

• Python 3.9+（用于 pip 安装）
• Node.js 14+（用于 npx 安装）
• 已安装并配置好 kubectl
• 可访问 Kubernetes 集群

Docker

# 从 Docker Hub 拉取镜像
docker pull rohitghumare64/kubectl-mcp-server:latest

# 或从 GitHub Container Registry 拉取镜像
docker pull ghcr.io/rohitg00/kubectl-mcp-server:latest

# 使用 stdio 传输运行
docker run -i -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest

# 使用 HTTP 传输运行
docker run -p 8000:8000 -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest --transport sse

开始使用

1. 测试服务器（可选）

在与您的 AI 助手集成之前，请先验证安装是否成功：

# 检查 kubectl 是否已配置
kubectl cluster-info

# 直接测试 MCP 服务器
kubectl-mcp-server info

# 列出所有可用工具
kubectl-mcp-server tools

# 尝试调用一个工具
kubectl-mcp-server call get_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 助手对话，并尝试以下指令：

故障排除：

“给我展示 kube-system 命名空间中的所有 Pod”
“为什么 nginx-deployment 的 Pod 会崩溃？”
“诊断 default 命名空间中的网络连接问题”

部署：

“创建一个包含 3 个副本的 nginx 部署”
“将我的前端部署扩展到 5 个副本”
“将 api-server 部署回滚到上一个版本”

成本与优化：

“哪些 Pod 正在使用最多的资源？”
“告诉我有哪些闲置资源正在浪费资金”
“分析 production 命名空间中的成本优化机会”

安全：

“审计所有命名空间中的 RBAC 权限”
“检查是否存在不安全的 Secret 和配置”
“列出具有特权访问权限运行的 Pod”

Helm：

“列出集群中的所有 Helm 发布”
“从 Bitnami 图表仓库安装 Redis”
“显示 my nginx-ingress Helm 发布的值”

多集群：

“列出所有可用的 Kubernetes 上下文”
“切换到 production 集群上下文”
“显示集群信息和版本”

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"]
    }
  }
}

完整功能集

253 个用于全面 Kubernetes 管理的 MCP 工具

类别	工具
Pods	get_pods, get_logs, get_pod_events, check_pod_health, exec_in_pod, cleanup_pods, get_pod_conditions, get_previous_logs
Deployments	get_deployments, create_deployment, scale_deployment, kubectl_rollout, restart_deployment
Workloads	get_statefulsets, get_daemonsets, get_jobs, get_replicasets
Services & Networking	get_services, get_ingress, get_endpoints, diagnose_network_connectivity, check_dns_resolution, trace_service_chain
Storage	get_persistent_volumes, get_pvcs, get_storage_classes
Config	get_configmaps, get_secrets, get_resource_quotas, get_limit_ranges
Cluster	get_nodes, get_namespaces, get_cluster_info, get_cluster_version, health_check, get_node_metrics, get_pod_metrics
RBAC & Security	get_rbac_roles, get_cluster_roles, get_service_accounts, audit_rbac_permissions, check_secrets_security, get_pod_security_info, get_admission_webhooks
CRDs	get_crds, get_priority_classes
Helm Releases	helm_list, helm_status, helm_history, helm_get_values, helm_get_manifest, helm_get_notes, helm_get_hooks, helm_get_all
Helm Charts	helm_show_chart, helm_show_values, helm_show_readme, helm_show_crds, helm_show_all, helm_search_repo, helm_search_hub
Helm Repos	helm_repo_list, helm_repo_add, helm_repo_remove, helm_repo_update
Helm Operations	install_helm_chart, upgrade_helm_chart, uninstall_helm_chart, helm_rollback, helm_test, helm_template, helm_template_apply
Helm Development	helm_create, helm_lint, helm_package, helm_pull, helm_dependency_list, helm_dependency_update, helm_dependency_build, helm_version, helm_env
Context	get_current_context, switch_context, list_contexts, list_kubeconfig_contexts
Diagnostics	diagnose_pod_crash, detect_pending_pods, get_evicted_pods, compare_namespaces
Operations	kubectl_apply, kubectl_create, kubectl_describe, kubectl_patch, delete_resource, kubectl_cp, backup_resource, label_resource, annotate_resource, taint_node, wait_for_condition
Autoscaling	get_hpa, get_pdb
Cost Optimization	get_resource_recommendations, get_idle_resources, get_resource_quotas_usage, get_cost_analysis, get_overprovisioned_resources, get_resource_trends, get_namespace_cost_allocation, optimize_resource_requests
Advanced	kubectl_generic, kubectl_explain, get_api_resources, port_forward, get_resource_usage, node_management
UI Dashboards	show_pod_logs_ui, show_pods_dashboard_ui, show_resource_yaml_ui, show_cluster_overview_ui, show_events_timeline_ui, render_k8s_dashboard_screenshot
GitOps (Flux/Argo)	gitops_apps_list, gitops_app_get, gitops_app_sync, gitops_app_status, gitops_sources_list, gitops_source_get, gitops_detect_engine
Cert-Manager	certs_list, certs_get, certs_issuers_list, certs_issuer_get, certs_renew, certs_status_explain, certs_challenges_list, certs_requests_list, certs_detect
Policy (Kyverno/Gatekeeper)	policy_list, policy_get, policy_violations_list, policy_explain_denial, policy_audit, policy_detect
Backup (Velero)	backup_list, backup_get, backup_create, backup_delete, restore_list, restore_create, restore_get, backup_locations_list, backup_schedules_list, backup_schedule_create, backup_detect
KEDA Autoscaling	keda_scaledobjects_list, keda_scaledobject_get, keda_scaledjobs_list, keda_triggerauths_list, keda_triggerauth_get, keda_hpa_list, keda_detect
Cilium/Hubble	cilium_policies_list, cilium_policy_get, cilium_endpoints_list, cilium_identities_list, cilium_nodes_list, cilium_status, hubble_flows_query, cilium_detect
Argo Rollouts/Flagger	rollouts_list, rollout_get, rollout_status, rollout_promote, rollout_abort, rollout_retry, rollout_restart, analysis_runs_list, flagger_canaries_list, flagger_canary_get, rollouts_detect
Cluster API	capi_clusters_list, capi_cluster_get, capi_machines_list, capi_machine_get, capi_machinedeployments_list, capi_machinedeployment_scale, capi_machinesets_list, capi_machinehealthchecks_list, capi_clusterclasses_list, capi_cluster_kubeconfig, capi_detect
KubeVirt VMs	kubevirt_vms_list, kubevirt_vm_get, kubevirt_vmis_list, kubevirt_vm_start, kubevirt_vm_stop, kubevirt_vm_restart, kubevirt_vm_pause, kubevirt_vm_unpause, kubevirt_vm_migrate, kubevirt_datasources_list, kubevirt_instancetypes_list, kubevirt_datavolumes_list, kubevirt_detect
Istio/Kiali	istio_virtualservices_list, istio_virtualservice_get, istio_destinationrules_list, istio_gateways_list, istio_peerauthentications_list, istio_authorizationpolicies_list, istio_proxy_status, istio_analyze, istio_sidecar_status, istio_detect
vCluster (vind)	vind_detect_tool, vind_list_clusters_tool, vind_status_tool, vind_get_kubeconfig_tool, vind_logs_tool, vind_create_cluster_tool, vind_delete_cluster_tool, vind_pause_tool, vind_resume_tool, vind_connect_tool, vind_disconnect_tool, vind_upgrade_tool, vind_describe_tool, vind_platform_start_tool
kind (K8s in Docker)	kind_detect_tool, kind_version_tool, kind_list_clusters_tool, kind_get_nodes_tool, kind_get_kubeconfig_tool, kind_export_logs_tool, kind_cluster_info_tool, kind_node_labels_tool, kind_create_cluster_tool, kind_delete_cluster_tool, kind_delete_all_clusters_tool, kind_load_image_tool, kind_load_image_archive_tool, kind_build_node_image_tool, kind_set_kubeconfig_tool

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 集群升级规划

核心能力

• 🤖 253 个强大工具 - 从 Pod 到安全，实现完整的 Kubernetes 管理
• 🎯 8 个 AI 工作流提示词 - 针对常见操作的预构建工作流
• 📊 8 个 MCP 资源 - 可浏览的 Kubernetes 数据展示
• 🎨 6 个交互式仪表板 - 用于可视化集群管理的 HTML UI 工具
• 🌐 26 个浏览器工具 - 支持云提供商的 Web 自动化
• 🔄 107 个生态工具 - GitOps、Cert-Manager、Policy、Backup、KEDA、Cilium、Rollouts、CAPI、KubeVirt、Istio、vCluster
• ⚡ 多传输方式 - stdio、SSE、HTTP、streamable-http
• 🔐 安全优先 - 非破坏性模式、密钥掩码、RBAC 验证
• 🏥 高级诊断 - 基于 AI 的故障排除和成本优化
• ☸️ 多集群支持 - 通过每个工具中的上下文参数可靶向任意集群
• 🎡 完整 Helm v3 - 全生命周期 Chart 管理
• 🔧 强大的 CLI - 符合 Shell 风格的工具发现与直接调用
• 🐳 云原生 - 可在集群内使用 kMCP 或 kagent 部署

使用 CLI

内置 CLI 让您无需 AI 助手即可探索和测试工具：

# 列出所有工具及其描述
kubectl-mcp-server tools -d

# 搜索与 Pod 相关的工具
kubectl-mcp-server grep "*pod*"

# 显示特定工具的 Schema
kubectl-mcp-server tools get_pods

# 直接调用工具
kubectl-mcp-server call get_pods '{"namespace": "kube-system"}'

# 从 stdin 管道传递 JSON
echo '{"namespace": "default"}' | kubectl-mcp-server call get_pods

# 检查依赖项
kubectl-mcp-server doctor

# 显示或切换 Kubernetes 上下文
kubectl-mcp-server context
kubectl-mcp-server context minikube

# 列出资源和提示词
kubectl-mcp-server resources
kubectl-mcp-server prompts

# 显示服务器信息
kubectl-mcp-server info

CLI 特性

• 结构化错误：提供可操作的错误消息及建议
• 彩色输出：便于人类阅读，并支持 JSON 模式以供脚本使用 (--json)
• NO_COLOR 支持：尊重 NO_COLOR 环境变量
• Stdin 支持：可将 JSON 参数管道传递给命令

高级配置

传输模式

服务器支持多种传输协议：

# stdio（默认） - 适用于 Claude Desktop、Cursor、Windsurf
kubectl-mcp-server
# 或：python -m kubectl_mcp_tool.mcp_server

# SSE - 用于 Web 客户端的服务器发送事件
kubectl-mcp-server --transport sse --port 8000

# HTTP - 用于 REST 客户端的标准 HTTP
kubectl-mcp-server --transport http --port 8000

# streamable-http - 用于 agentgateway 集成
kubectl-mcp-server --transport streamable-http --port 8000

传输选项：

• --transport：选择 stdio、sse、http、streamable-http（默认：stdio）
• --host：绑定地址（默认：0.0.0.0）
• --port：网络传输使用的端口（默认：8000）
• --disable-destructive（或 --non-destructive）：阻止破坏性操作（允许创建/更新，禁止删除）
• --read-only：阻止所有写操作

环境变量

核心设置：

变量	描述	默认值
KUBECONFIG	kubeconfig 文件路径	~/.kube/config
MCP_DEBUG	启用详细日志记录	false
MCP_LOG_FILE	日志文件路径	无（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	必需的 OAuth 范围	mcp:tools

浏览器自动化（可选）：

变量	描述	默认值
MCP_BROWSER_ENABLED	启用浏览器自动化工具	false
MCP_BROWSER_PROVIDER	云提供商（browserbase/browseruse）	无
MCP_BROWSER_PROFILE	持久化配置文件路径	无
MCP_BROWSER_CDP_URL	远程 CDP WebSocket URL	无
MCP_BROWSER_PROXY	代理服务器 URL	无

可选：交互式仪表板（6 个 UI 工具）

获取精美的 HTML 仪表板，用于可视化集群管理。

安装：

# 安装带 UI 支持的版本
pip install kubectl-mcp-server[ui]

6 个仪表板工具：

• 📊 show_pods_dashboard_ui - 实时 Pod 状态表格
• 📝 show_pod_logs_ui - 带搜索功能的交互式日志查看器
• 🎯 show_cluster_overview_ui - 完整的集群仪表板
• ⚡ show_events_timeline_ui - 带过滤功能的事件时间线
• 📄 show_resource_yaml_ui - 带语法高亮的 YAML 查看器
• 📸 render_k8s_dashboard_screenshot - 将仪表板导出为 PNG

特性：

• 🎨 针对终端优化的暗色主题（Catppuccin）
• 🔄 对不兼容客户端优雅地回退到 JSON
• 🖼️ 截图渲染以确保通用兼容性
• 🚀 无外部依赖

兼容性：Goose、LibreChat、Nanobot（完整 HTML UI）| Claude Desktop、Cursor 等（JSON + 截图）

可选：浏览器自动化（26 个工具）

通过 agent-browser 集成，自动执行基于 Web 的 Kubernetes 操作。

快速设置：

# 安装 agent-browser
npm install -g agent-browser
agent-browser install

# 启用浏览器工具
export MCP_BROWSER_ENABLED=true
kubectl-mcp-server

您可以做的事情：

• 🌐 通过 Ingress URL 测试已部署的应用
• 📸 截取 Grafana、ArgoCD 或任何 K8s 仪表板的截图
• ☁️ 自动化云控制台操作（EKS、GKE、AKS）
• 🏥 对 Web 应用进行健康检查
• 📄 将监控仪表板导出为 PDF
• 🔐 使用持久化会话测试认证流程

可用的 26 个工具：browser_open、browser_screenshot、browser_click、browser_fill、browser_test_ingress、browser_screenshot_grafana、browser_health_check，以及 另外 19 个

高级特性：

• 云提供商：Browserbase、Browser Use
• 持久化浏览器配置文件
• 远程 CDP 连接
• 会话管理

可选：kubectl-mcp-app（8 个交互式 UI 仪表板）

一个独立的 npm 包，利用 MCP ext-apps SDK 提供美观、交互式的 UI 仪表板，用于 Kubernetes 管理。

安装：

# 安装 kubectl-mcp-app
npm install kubectl-mcp-app

通过 npm

npm install -g kubectl-mcp-app

或者通过 npx（无需安装）

npx kubectl-mcp-app

**Claude Desktop 配置：**

```json
{
  "mcpServers": {
    "kubectl-app": {
      "command": "npx",
      "args": ["kubectl-mcp-app"]
    }
  }
}

8 个交互式 UI 工具：

工具	描述
k8s-pods	带有筛选、排序和状态指示器的交互式 Pod 查看器
k8s-logs	支持语法高亮和搜索的实时日志查看器
k8s-deploy	包含发布状态、扩缩容和回滚功能的部署仪表板
k8s-helm	提供升级/回滚操作的 Helm 发布管理器
k8s-cluster	显示节点健康状况和资源指标的集群概览
k8s-cost	具有浪费检测和建议的成本分析工具
k8s-events	支持按类型过滤和分组的事件时间线
k8s-network	展示 Service/Pod/Ingress 的网络拓扑图

功能：

• 🎨 暗色/亮色主题支持
• 📊 实时数据可视化
• 🖱️ 交互式操作（扩缩容、重启、删除）
• 🔗 与 kubectl-mcp-server 的无缝集成

更多信息：请参阅 kubectl-mcp-app/README.md 获取完整文档。

企业级：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 标准的提供商。

适用场景：多租户环境、合规性要求、审计日志记录。

集成与生态系统

Docker MCP 工具包

可与 Docker MCP 工具包 一起使用：

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

agentregistry

从中心化的 agentregistry 安装：

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

# 安装 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 服务器：

# 使用 streamable-http 启动
kubectl-mcp-server --transport streamable-http --port 8000

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

# 启动网关
agentgateway --config gateway.yaml

客户端可连接到 http://localhost:3000/mcp 来统一访问所有 253 个工具。

集群内部署

选项 1：kMCP（推荐）

使用 kMCP 部署——一个用于 MCP 服务器的控制平面：

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

# 部署 kubectl-mcp-server（最简单）
kmcp deploy package --deployment-name kubectl-mcp-server \
   --manager npx --args kubectl-mcp-server

# 或者使用 Docker 镜像
kmcp deploy --file deploy/kmcp/kmcp.yaml --image rohitghumare64/kubectl-mcp-server:latest

详情请参阅 kMCP 快速入门。

选项 2：标准 Kubernetes

使用 kubectl/kustomize 部署：

# 推荐使用 kustomize
kubectl apply -k deploy/kubernetes/

# 或者单独应用清单
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

# 通过端口转发访问
kubectl port-forward -n kubectl-mcp svc/kubectl-mcp-server 8000:8000

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

选项 3：kagent（AI 代理框架）

与 kagent 集成——一个 CNCF Kubernetes 原生的 AI 代理框架：

# 安装 kagent
brew install kagent
kagent install --profile demo

# 注册为 ToolServer
kubectl apply -f deploy/kagent/toolserver-stdio.yaml

# 打开仪表板
kagent dashboard

您的 AI 代理现在可以访问所有 253 个 Kubernetes 工具。详情请参阅 kagent 快速入门。

架构

┌─────────────────┐     ┌──────────────────┐     ┌─────────────────┐
│   AI 助手  │────▶│   MCP 服务器     │────▶│  Kubernetes API │
│ (Claude/Cursor) │◀────│ (kubectl-mcp)    │◀────│    (kubectl)    │
└─────────────────┘     └──────────────────┘     └─────────────────┘

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

模块化结构

kubectl_mcp_tool/
├── mcp_server.py          # 主服务器（FastMCP，传输协议）
├── tools/                  # 按类别组织的 253 个 MCP 工具
│   ├── pods.py            # Pod 管理与诊断
│   ├── deployments.py     # Deployments、StatefulSets、DaemonSets
│   ├── core.py            # Namespaces、ConfigMaps、Secrets
│   ├── cluster.py         # 上下文/集群管理
│   ├── networking.py      # Services、Ingress、NetworkPolicies
│   ├── storage.py         # PVCs、StorageClasses、PVs
│   ├── security.py        # RBAC、ServiceAccounts、PodSecurity
│   ├── helm.py            # 完整的 Helm v3 操作
│   ├── operations.py      # kubectl apply/patch/describe 等
│   ├── diagnostics.py     # 指标、命名空间比较
│   ├── cost.py            # 资源优化与成本分析
│   ├── ui.py              # MCP-UI 交互式仪表板
│   ├── gitops.py          # GitOps（Flux/ArgoCD）
│   ├── certs.py           # Cert-Manager
│   ├── policy.py          # Policy（Kyverno/Gatekeeper）
│   ├── backup.py          # Backup（Velero）
│   ├── keda.py            # KEDA 自动缩放
│   ├── cilium.py          # Cilium/Hubble 网络可观ability
│   ├── rollouts.py        # Argo Rollouts/Flagger
│   ├── capi.py            # Cluster API
│   ├── kubevirt.py        # KubeVirt VMs
│   ├── kiali.py           # Istio/Kiali 服务网格
│   └── vind.py            # vCluster（虚拟集群）
├── resources/              # 8 个用于数据暴露的 MCP 资源
├── prompts/                # 8 个用于工作流的 MCP 提示
└── cli/                    # CLI 界面

代理技能（适用于 AI 编码代理的 25 种技能）

借助我们的 Agent Skills 库，为您的 AI 编码代理扩展 Kubernetes 专业知识。这些技能提供了代理可按需加载的专业知识和工作流。

快速安装

# 将所有技能复制到 Claude
cp -r kubernetes-skills/claude/* ~/.claude/skills/

# 或者仅安装特定技能
cp -r kubernetes-skills/claude/k8s-helm ~/.claude/skills/

可用技能（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-service-mesh, k8s-cilium
工具	k8s-browser, k8s-cli

转换为其他代理

使用 SkillKit 将技能转换为您偏好的 AI 代理格式：

npm install -g skillkit

# 转换为 Cursor 格式
skillkit translate kubernetes-skills/claude --to cursor --output .cursor/rules/

# 转换为 Codex 格式
skillkit translate kubernetes-skills/claude --to codex --output ./

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

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

多集群支持

通过自然语言无缝管理多个 Kubernetes 集群。所有工具均支持可选的 context 参数，以便在不切换上下文的情况下直接操作任意集群。

上下文参数（v1.15.0）

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

与您的 AI 助手对话：

“列出生产集群中的 Pod”
“从 staging 上下文中获取部署”
“显示 dev 集群中 api-pod 的日志”
“比较生产与 staging 集群之间的命名空间”

直接调用工具并指定上下文：

# 指定特定集群上下文
kubectl-mcp-server call get_pods '{"namespace": "default", "context": "production"}'

# 从 staging 获取部署
kubectl-mcp-server call get_deployments '{"namespace": "app", "context": "staging"}'

# 在生产集群中安装 Helm Chart
kubectl-mcp-server call install_helm_chart '{"name": "redis", "chart": "bitnami/redis", "namespace": "cache", "context": "production"}'

# 比较跨集群资源
kubectl-mcp-server call compare_namespaces '{"namespace1": "prod-ns", "namespace2": "staging-ns", "context": "production"}'

上下文管理

与您的 AI 助手对话：

“列出所有可用的 Kubernetes 上下文”
“切换到生产集群”
“向我展示 staging 上下文的详细信息”
“我现在连接的是哪个集群？”

或直接使用 CLI：

kubectl-mcp-server context                    # 显示当前上下文
kubectl-mcp-server context production         # 切换上下文
kubectl-mcp-server call list_contexts_tool    # 通过 MCP 列出所有上下文

工作原理

• 如果未指定 context，工具将使用您当前的 kubectl 上下文。
• 如果指定了 context，工具将直接操作该集群。
• 响应中会包含 "context": "production" 或 "context": "current"，以明确上下文。
• 适用于所有 kubeconfig 配置，并尊重 KUBECONFIG 环境变量。
• 无需切换上下文即可进行跨集群操作。

开发与测试

设置开发环境

# 克隆仓库
git clone https://github.com/rohitg00/kubectl-mcp-server.git
cd kubectl-mcp-server

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows 系统：venv\Scripts\activate

# 安装开发依赖
pip install -r requirements-dev.txt

运行测试

# 运行所有测试
pytest tests/ -v

# 运行特定测试文件
pytest tests/test_tools.py -v

# 带覆盖率运行
pytest tests/ --cov=kubectl_mcp_tool --cov-report=html

# 仅运行单元测试
pytest tests/ -v -m unit

测试结构

tests/
├── __init__.py          # 测试包
├── conftest.py          # 共享 fixture 和 mock
├── test_tools.py        # 253 个 MCP 工具的单元测试
├── test_resources.py    # 8 个 MCP 资源的测试
├── test_prompts.py      # 8 个 MCP 提示词的测试
└── test_server.py       # 服务器初始化测试

234 个测试涵盖： 工具注册、资源暴露、提示词生成、服务器初始化、非破坏性模式、敏感信息屏蔽、错误处理、传输方法、CLI 命令、浏览器自动化以及生态系统工具。

代码质量

# 格式化代码
black kubectl_mcp_tool tests

# 排序导入
isort kubectl_mcp_tool tests

# 静态代码分析
flake8 kubectl_mcp_tool tests

# 类型检查
mypy kubectl_mcp_tool

贡献

我们非常欢迎各种形式的贡献！无论是 bug 报告、功能请求、文档改进，还是代码贡献。

贡献方式：

• 🐛 通过 GitHub Issues 报告 bug
• 💡 提出功能或改进建议
• 📝 改进文档
• 🔧 提交 pull request
• ⭐ 如果您觉得项目有用，请为它点赞！

开发设置： 请参阅上方的 开发与测试 部分。

提交 PR 前：

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

支持与社区

• 📖 文档
• 💬 GitHub Discussions
• 🐛 问题追踪器
• 🎯 功能请求
• 🌟 agentregistry 个人主页

许可证

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

链接与资源

软件包仓库：

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

项目：

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

生态系统：

• 📚 模型上下文协议
• ☸️ Kubernetes 官方文档

---

专为 Kubernetes 和 AI 社区用心打造

如果 kubectl-mcp-server 让您的 DevOps 工作更加轻松，请在 GitHub 上给它点个赞吧！

kubectl-mcp-server 快速上手指南

kubectl-mcp-server 是一个基于 Model Context Protocol (MCP) 的开源工具，让你能够通过自然语言与 AI 助手对话，直接管理和诊断 Kubernetes 集群。无需记忆复杂的 kubectl 命令，即可实现故障排查、应用部署、成本优化和安全审计。

1. 环境准备

在开始之前，请确保你的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• Kubernetes 访问权限:
  • 已安装并配置好 kubectl 命令行工具。
  • 拥有有效的 kubeconfig 文件（通常位于 ~/.kube/config），且能正常连接集群。
  • 验证命令：kubectl cluster-info
• 运行环境 (二选一):
  • Node.js: 版本 14+ (推荐使用 npx 方式，无需手动安装)。
  • Python: 版本 3.9+ (如果使用 pip 安装)。
• AI 助手客户端: 支持 MCP 协议的客户端，如 Claude Desktop, Cursor, Windsurf, GitHub Copilot 等。

国内开发者提示: 如果下载 npm 或 pip 包速度较慢，建议配置国内镜像源。

• npm: npm config set registry https://registry.npmmirror.com
• pip: pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

2. 安装步骤

你可以选择通过 npx (推荐，零安装) 或 pip 进行安装。

方案 A：使用 npx (推荐)

无需全局安装，直接运行即可，最适合快速尝试。

# 直接运行 (首次会自动下载)
npx -y kubectl-mcp-server

# 或者全局安装以加快启动速度
npm install -g kubectl-mcp-server

方案 B：使用 pip (Python)

如果你更习惯 Python 环境，或需要启用交互式 UI 仪表盘功能。

# 标准安装
pip install kubectl-mcp-server

# 推荐：安装包含交互式 UI 仪表盘的版本
pip install kubectl-mcp-server[ui]

方案 C：Docker 运行

适合容器化环境或不想污染本地环境的场景。

# 拉取镜像并运行 (挂载 kubeconfig)
docker run -i -v $HOME/.kube:/root/.kube:ro rohitghumare64/kubectl-mcp-server:latest

3. 基本使用

安装完成后，你需要将工具配置到你的 AI 助手客户端中，然后通过自然语言发起指令。

第一步：配置 AI 助手

根据你的 AI 客户端，将以下配置添加到对应的配置文件中。配置后需重启 AI 客户端。

选项 1: Claude Desktop

编辑文件：~/Library/Application Support/Claude/claude_desktop_config.json (Mac) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows)

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

选项 2: Cursor / Windsurf

编辑项目根目录或全局配置中的 .cursor/mcp.json 或 ~/.config/windsurf/mcp.json：

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

选项 3: GitHub Copilot (VS Code)

在 VS Code 的 settings.json 中添加：

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

注意: 如果使用 pip 安装而非 npx，请将 "command" 改为 "python"，"args" 改为 ["-m", "kubectl_mcp_tool.mcp_server"]。

第二步：开始对话

重启 AI 助手后，直接在对话框中使用自然语言操作集群。

常用指令示例：

• 故障排查:

  "为什么我的 nginx-deployment pod 一直在崩溃？" "诊断 default 命名空间下的网络连接问题。"

• 资源管理:

  "列出 kube-system 命名空间下的所有 Pod。" "显示哪些 Pod 浪费了最多的资源。"

• 应用部署:

  "创建一个包含 3 个副本的 Redis 部署。" "将 frontend 部署扩容到 5 个副本。"

• 安全审计:

  "审计所有命名空间的 RBAC 权限。" "检查是否有使用特权模式运行的 Pod。"

• Helm 管理:

  "列出集群中所有的 Helm Release。" "从 Bitnami 仓库安装 Redis。"

第三步：CLI 独立测试 (可选)

在不通过 AI 助手的情况下，你也可以直接在终端测试服务器功能：

# 查看服务器信息
kubectl-mcp-server info

# 列出所有可用工具
kubectl-mcp-server tools

# 直接调用工具获取 Pod 列表
kubectl-mcp-server call get_pods '{"namespace": "kube-system"}'