kubeaid-mcp

An MCP (Model Context Protocol) server that exposes a Kubernetes cluster to any MCP-compatible AI client (Claude Code, Claude Desktop, Cursor, ...). The client launches the server as a subprocess and talks to it over stdio (JSON-RPC 2.0); the server translates tool calls into Kubernetes API calls via @kubernetes/client-node.

Built in TypeScript on the NitroStack MCP framework.

See design.md for the architecture.

Demo

Related MCP server: MCP Remote Server for Kubernetes

Tools

Every tool accepts an optional context argument to target a specific kubeconfig context. Omit it to use the server's default context.

Write tools (opt-in)

These are registered only when KUBEAID_ALLOW_WRITES=true. Each accepts an optional dry_run to simulate the change server-side without persisting it.

Prompts

Prompts are user-invoked workflow templates (surfaced as slash commands / menu items in the client). Unlike tools, a prompt does not touch the cluster — it returns a message that guides the model through a task using the tools above.

Installation

Requires Node.js 20+. Build the server once, then register it with your AI client(s).

1. Build the server

git clone https://github.com/1shubham7/kubeaid-mcp-ts.git
cd kubeaid-mcp-ts
npm install
npm run build        # compiles TypeScript to dist/ (entry: dist/index.js)

Note the absolute path to the entry point — the AI clients need it:

echo "$(pwd)/dist/index.js"

For local iteration you can also run npm run dev (NitroStack's dev server with hot reload), which is handy with NitroStudio as a visual MCP client.

2. Register with Claude Code

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

With no KUBEAID_CONTEXT set, the server follows your kubeconfig's current-context live, so kubectl config use-context <name> switches the target cluster without re-registering. Pin a fixed default by adding -e KUBEAID_CONTEXT=kind-kubeaid if you'd rather it never move.

Read tools only are exposed by default. To enable the mutating tools (apply/patch/delete/scale/rollout), pass -e KUBEAID_ALLOW_WRITES=true, and list any production contexts as protected so they can never be written to:

claude mcp add kubeaid \
  -e KUBEAID_ALLOW_WRITES=true \
  -e KUBEAID_PROTECTED_CONTEXTS=prod-cluster,another-prod-cluster \
  -- node "$(pwd)/dist/index.js"

3. Register with Claude Desktop

Recent Claude Desktop builds gate local MCP servers behind a setting, so order matters:

1. Enable local MCP: Settings → Developer → Local MCP servers. Local stdio servers are off by default; opening/enabling this is required.

2. Edit the config: on that page click Edit Config — it opens the file the app actually reads (~/.config/Claude/claude_desktop_config.json on Linux; macOS ~/Library/Application Support/Claude/; Windows %APPDATA%\Claude\). Add a top-level mcpServers key, using the absolute path from step 1:

   {
     "mcpServers": {
       "kubeaid": {
         "command": "node",
         "args": ["/home/you/kubeaid-mcp-ts/dist/index.js"]
       }
     }
   }

   If the file already has other keys (e.g. preferences), keep them and add mcpServers alongside — don't overwrite the file.

3. Fully quit and reopen Claude Desktop. Closing the window is not enough on Linux — the process must actually exit. The server then appears under Settings → Developer → Local MCP servers.

Enabling writes: add the options via an env block — e.g. make the local cluster writable while protecting production:

{
  "mcpServers": {
    "kubeaid": {
      "command": "node",
      "args": ["/home/you/kubeaid-mcp-ts/dist/index.js"],
      "env": {
        "KUBEAID_CONTEXT": "kind-kubeaid",
        "KUBEAID_ALLOW_WRITES": "true",
        "KUBEAID_PROTECTED_CONTEXTS": "prod-cluster,another-prod-cluster"
      }
    }
  }
}

Add "KUBEAID_ALLOW_EXEC": "true" for the exec_command tool, and re-run step 3 after changing the config.

Notes:

• command/args must use absolute paths; GUI apps don't inherit your shell PATH, and Node needs the absolute path to dist/index.js.

• Destructive tools carry a destructiveHint, so Desktop still prompts you per action — the env vars control what's possible; the prompt is your confirmation.

• If your account is enterprise-managed, an admin policy can disable local MCP entirely, in which case no local config will load.

Safety

The server is read-only by default — the read tools only call non-mutating verbs (get, list, watch, log). Mutating tools exist but are gated:

• KUBEAID_ALLOW_WRITES=true must be set for apply_manifest, patch_resource, delete_resource, scale_deployment, and rollout_restart to be exposed at all.

• KUBEAID_ALLOW_EXEC=true (in addition) is required for exec_command.

• KUBEAID_PROTECTED_CONTEXTS lists contexts that may never be written to or exec'd into, even with the flags above — put your production contexts here.

• Tools are annotated (readOnlyHint / destructiveHint) so clients can prompt before risky actions.

The server authenticates with your kubeconfig credentials, so it can only do what your account is already permitted to do.

Configuration

All configuration is read from the environment at startup. An MCP client passes these via the server entry's env block (Claude Desktop) or -e flags (Claude Code). A local .env file also works for development — see .env.example.

Development

Drive the server by hand (no AI client needed) to inspect the raw protocol and confirm which tools are registered:

npm run build
KUBECONFIG=~/.kube/config node scripts/drive.mjs   # initialize + tools/list + prompts/list