KubeAid MCP

一个用于KubeAid管理的Kubernetes集群的MCP服务器。 将其接入Claude Code、Claude Desktop、Cursor或任何兼容MCP的客户端， 即可提出诸如*"哪些应用不同步？"、"为什么kube-prometheus降级了？"或"同步cert-manager应用"*等问题——模型通过调用此服务器的工具来回答，这些工具通过您自己的kubeconfig凭据与您的集群通信。

基于官方@modelcontextprotocol/sdk和@kubernetes/client-node用TypeScript构建。

作者： Deep Poharkar

为什么专门针对KubeAid？

KubeAid以GitOps方式运行集群：每个应用都是从你的kubeaid-config仓库生成的ArgoCD Application，并且默认禁用自动同步——Git与集群之间的漂移是正常的，需要等待有意的同步。通用的Kubernetes助手不理解这种工作流。此服务器理解：

• ArgoCD Application CR是一等公民：同步状态、健康状态、失败条件和漂移资源只需一次工具调用即可获取。

• 同步被建模为KubeAid中明确的"立即部署"决策——通过选择加入的标志进行门控，支持dry_run，并且绝不允许在你标记为受保护的上下文中执行。

• 捆绑的提示词编码了KubeAid的操作习惯：同步前先审查漂移，在kubeaid-config仓库中修复问题，而不是手动编辑集群。

工具

读取工具——始终注册：

写入工具——仅在KUBEAID_MCP_ALLOW_WRITES=true时注册：

每个工具都接受可选的context参数，以便从单个服务器进程定位kubeconfig中的任何集群。

提示词

提示词在客户端中作为斜杠命令/菜单项出现，并使用上述工具引导模型完成工作流：

快速开始

需要Node.js 20+。

git clone <your-repo-url> kubeaid-mcp
cd kubeaid-mcp
npm install
npm run build

Claude Code

claude mcp add kubeaid -- node "$(pwd)/dist/index.js"

默认只读。要在保持生产环境不可触碰的同时启用写入：

claude mcp add kubeaid \
  -e KUBEAID_MCP_ALLOW_WRITES=true \
  -e KUBEAID_MCP_PROTECTED_CONTEXTS=prod-cluster-1,prod-cluster-2 \
  -- node "$(pwd)/dist/index.js"

Claude Desktop

启用设置 → 开发者 → 本地MCP服务器，然后添加到该页面打开的配置文件中：

{
  "mcpServers": {
    "kubeaid": {
      "command": "node",
      "args": ["/absolute/path/to/kubeaid-mcp/dist/index.js"],
      "env": {
        "KUBEAID_MCP_ALLOW_WRITES": "true",
        "KUBEAID_MCP_PROTECTED_CONTEXTS": "prod-cluster-1"
      }
    }
  }
}

之后完全退出并重新打开应用。

配置

所有配置都是环境变量，在启动时读取一次：

安全模型

三个独立的层：

1. 能力门控 — 禁用写入（默认）时，变更工具永远不会注册，因此模型甚至无法看到它们。

2. 受保护的上下文 — 每个变更处理器都会根据KUBEAID_MCP_PROTECTED_CONTEXTS重新检查目标上下文，并拒绝受保护的上下文，无论模型要求什么。

3. 客户端确认 — 工具带有MCP readOnlyHint/destructiveHint注释，因此行为良好的客户端会在风险调用前提示你。

服务器本身不持有任何凭据；它只能执行你的kubeconfig身份通过RBAC已被授权执行的操作。

开发

npm run typecheck   # strict TS, no emit
npm run build       # compile to dist/
npm run smoke       # spawn the server, MCP handshake, list tools + prompts
KUBEAID_MCP_ALLOW_WRITES=true npm run smoke   # verify write tools register

冒烟测试不需要集群——它通过stdio驱动原始JSON-RPC协议。

路线图

• check_chart_updates：将部署的图表版本与上游KubeAid argocd-helm-charts目录进行比较。

• 密封秘密辅助工具：列出SealedSecret状态，标记失败的解封。

• Prometheus/Alertmanager工具：从KubeAid附带的kube-prometheus堆栈中显示触发的警报。

致谢

• KubeAid by Obmondo — 此服务器所构建的集群管理栈。

• Argo CD — KubeAid底下的GitOps引擎。

许可证

MIT © 2026 Deep Poharkar