KubeAid MCP

An MCP server for KubeAid-managed Kubernetes clusters. Plug it into Claude Code, Claude Desktop, Cursor or any MCP-compatible client and ask questions like "which apps are out of sync?", "why is kube-prometheus degraded?" or "sync the cert-manager app" — the model answers by calling this server's tools, which talk to your cluster through your own kubeconfig credentials.

Built in TypeScript on the official @modelcontextprotocol/sdk and @kubernetes/client-node.

Author: Deep Poharkar

Why KubeAid-specific?

KubeAid runs clusters the GitOps way: every application is an ArgoCD Application generated from your kubeaid-config repo, and auto-sync is disabled by default — drift between Git and the cluster is normal and waits for a deliberate sync. A generic Kubernetes assistant doesn't understand that workflow. This server does:

• The ArgoCD Application CR is a first-class citizen: sync status, health, failing conditions and drifted resources are one tool call away.

• Syncing is modeled as the explicit "deploy now" decision it is in KubeAid — gated behind an opt-in flag, with dry_run support, and never allowed on contexts you mark as protected.

• The bundled prompts encode KubeAid operational habits: review drift before syncing, fix things in the kubeaid-config repo rather than hand-editing the cluster.

Tools

Read tools — always registered:

Write tools — registered only when KUBEAID_MCP_ALLOW_WRITES=true:

Every tool takes an optional context argument to target any cluster in your kubeconfig from a single server process.

Prompts

Prompts appear as slash commands / menu items in the client and walk the model through a workflow using the tools above:

Quick start

Requires 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"

Read-only by default. To enable writes while keeping production untouchable:

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

Enable Settings → Developer → Local MCP servers, then add to the config file that page opens:

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

Fully quit and reopen the app afterwards.

Configuration

All configuration is environment variables, read once at startup:

Safety model

Three independent layers:

1. Capability gating — with writes disabled (the default), mutating tools are never registered, so the model cannot even see them.

2. Protected contexts — every mutating handler re-checks the target context against KUBEAID_MCP_PROTECTED_CONTEXTS and refuses protected ones, whatever the model asks for.

3. Client confirmation — tools carry MCP readOnlyHint/destructiveHint annotations, so well-behaved clients prompt you before risky calls.

The server holds no credentials of its own; it can only do what your kubeconfig identity is already authorized to do via RBAC.

Development

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

The smoke test needs no cluster — it drives the raw JSON-RPC protocol over stdio.

Roadmap

• check_chart_updates: compare deployed chart versions against the upstream KubeAid argocd-helm-charts directory.

• Sealed-secrets helpers: list SealedSecret status, flag failed unseals.

• Prometheus/Alertmanager tools: surface firing alerts from the kube-prometheus stack KubeAid ships.

Acknowledgements

• KubeAid by Obmondo — the cluster management stack this server is built for.

• Argo CD — the GitOps engine underneath KubeAid.

License

MIT © 2026 Deep Poharkar