kube-mcp

A Model Context Protocol (MCP) server that lets AI assistants (Claude, VS Code extension, etc.) query multiple Kubernetes clusters simultaneously using natural language.

Each cluster runs a lightweight agent that connects back to a central MCP server. The AI talks to the central server and commands are routed to the right cluster transparently.

Architecture

Claude / VS Code Extension
        │  MCP over HTTP
        ▼
┌─────────────────────┐
│   Central Server    │  ← single endpoint, aggregates all clusters
│  (MCP + WebSocket)  │
└──────┬──────────────┘
       │ WebSocket (wss://)
  ┌────┴────┐
  │         │
┌─▼──┐   ┌──▼──┐
│ A  │   │  B  │   cluster agents (one per cluster)
└────┘   └─────┘
  k8s      k8s       in-cluster kubectl / helm (read-only)

• Central server — exposes an MCP HTTP endpoint and manages WebSocket connections from cluster agents.

• Cluster agent — deployed as a Kubernetes Deployment with a Helm chart. Uses the in-cluster service account for read-only kubectl/helm access and connects outbound to the central server.

Features

• Query any connected cluster from a single MCP endpoint

• Per-cluster token authentication (each cluster has its own secret)

• Read-only by default — only get, list, watch verbs allowed

• Command injection protection — all arguments passed as arrays, no shell execution

• Blocked flags — --server, --kubeconfig, --token, etc. are rejected

• Output size cap (2 MB) and command timeout (55 s)

• Structured JSON logging with audit trail

• Liveness and readiness probes on the agent

• WebSocket reconnect with exponential backoff

• Per-IP WebSocket connection limit

• Agent reports kubectl and helm versions to the central server on connect

Available MCP Tools

Example prompts

• "What pods are running in kube-system on my prod cluster?"

• "List all deployments across all clusters"

• "Show me the Helm releases installed on staging"

• "Describe the failing pod on eu-cluster"

Prerequisites

• Kubernetes clusters (1.24+)

• Helm 3

• A container registry to push the images to

• An ingress with TLS for the central server (recommended)

Quick Start

1. Build and push images

# Central server
docker build -t <your-registry>/central-server:latest \
  -f packages/central-server/Dockerfile .
docker push <your-registry>/central-server:latest

# Cluster agent
docker build -t <your-registry>/cluster-agent:latest \
  -f packages/cluster-agent/Dockerfile .
docker push <your-registry>/cluster-agent:latest

2. Deploy the central server

Generate an MCP API key and a token for each cluster agent:

openssl rand -hex 32   # MCP API key (for Claude / VS Code)
openssl rand -hex 32   # token for cluster-1
openssl rand -hex 32   # token for cluster-2

Install the Helm chart:

helm install central-server ./helm/central-server \
  --namespace mcp-system --create-namespace \
  --set image.repository=<your-registry>/central-server \
  --set config.mcpApiKey="<mcp-api-key>" \
  --set config.clusterTokens.prod-us="<token-for-prod-us>" \
  --set config.clusterTokens.staging-eu="<token-for-staging-eu>" \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=mcp.example.com \
  --set ingress.tls[0].hosts[0]=mcp.example.com \
  --set ingress.tls[0].secretName=mcp-tls

The ingress must support WebSocket upgrades. For nginx-ingress add these annotations:

nginx.ingress.kubernetes.io/proxy-read-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-send-timeout: "3600"
nginx.ingress.kubernetes.io/proxy-http-version: "1.1"

3. Deploy the cluster agent (repeat per cluster)

helm install cluster-agent ./helm/cluster-agent \
  --namespace mcp-system --create-namespace \
  --set image.repository=<your-registry>/cluster-agent \
  --set config.centralServerUrl=wss://mcp.example.com \
  --set config.clusterName=prod-us \
  --set config.agentToken="<token-for-prod-us>"

Each cluster's agentToken must match the corresponding entry in clusterTokens on the central server.

4. Connect your MCP client

VS Code (Claude extension) — .mcp.json in your project root:

{
  "mcpServers": {
    "multi-cluster-k8s": {
      "type": "http",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "X-Api-Key": "<mcp-api-key>"
      }
    }
  }
}

Claude.ai — Remote MCP server URL:

https://mcp.example.com/mcp?api_key=<mcp-api-key>

5. Verify

Ask Claude: "List all connected clusters" — you should see your clusters with their kubectl and helm versions.

Configuration Reference

Central Server

Cluster Agent

Security

• Per-cluster tokens — every agent authenticates with its own unique token. A compromised cluster cannot impersonate another.

• Timing-safe comparison — token verification iterates all registered tokens without early exit to prevent timing attacks.

• Read-only RBAC — the cluster agent's ClusterRole only grants get, list, watch verbs.

• Verb allowlist — the executor validates every command against an allowlist before running it.

• Blocked flags — flags like --server, --kubeconfig, --token, --exec are rejected even if the verb is allowed.

• No shell execution — all commands are passed as argument arrays to child_process.spawn, preventing injection.

• Non-root containers — both images run as UID 1000 with a read-only root filesystem.

• Output cap — command output is capped at 2 MB to prevent memory exhaustion.

Repository Structure

.
├── packages/
│   ├── central-server/     # MCP server + WebSocket hub
│   └── cluster-agent/      # In-cluster Kubernetes agent
├── helm/
│   ├── central-server/     # Helm chart for the central server
│   └── cluster-agent/      # Helm chart for the cluster agent
├── .dockerignore
├── .gitignore
└── package.json            # npm workspace root

Development

npm install
npm run build        # build both packages

Each package has its own tsconfig.json and compiles to dist/.

License

MIT — see LICENSE.