Kubernetes Assistant with MCP

A small, readable Model Context Protocol server that lets an AI assistant diagnose a broken application on a local Kubernetes cluster, with guardrails you can explain and audit.

Companion demo for the talk "Build Your Own AI Kubernetes Assistant with MCP".

MCP host (Claude Code / Claude Desktop)
        │  stdio
        ▼
server/server.py ── ServiceAccount token ──▶ kube-apiserver  (RBAC has the final say)
        │
        └── audit.log  (append-only JSON lines)

Features

The diagnose_pod prompt is a runbook: inspect pods, events and logs, then report root cause, evidence and a proposed fix, and ask before any restart.

Related MCP server: k8s-ops-mcp-agent

Defence in depth

1. Server guardrails: input validation, namespace allow-list, log-line cap, a single write tool that can only restart.

2. Kubernetes RBAC (k8s/rbac.yaml): the server connects as a dedicated ServiceAccount that can read pods, pod logs and events, and patch deployments in shop only. No secrets, no pods/exec, no delete. Even a bug in the server cannot exceed these permissions. scripts/prove-rbac.sh demonstrates it with kubectl auth can-i.

3. Audit trail: every call, including rejections and errors, is appended to audit.log.

Requirements

Docker, kind, kubectl, Python 3.10+, uv. scripts/preflight.sh checks them (and installs missing ones via Homebrew on macOS).

Quick start

./scripts/preflight.sh          # verify tooling
./scripts/setup.sh              # kind cluster, namespaces, demo apps, RBAC, ServiceAccount kubeconfig (idempotent)
uv run python tests/client.py   # exercise every tool and guardrail over stdio
./scripts/register-claude.sh    # register the server with Claude Code (project scope)

Then start claude in this directory and approve the k8s-assistant project server once.

The demo scenario

Namespace shop runs cart and orders-db (healthy) and checkout, which crash-loops because it resolves the wrong database host (connection refused: db:5432). scripts/fix-db.sh creates the missing db Service, after which a restart recovers checkout. The full live script is in DEMO.md.

Scripts

Terminal setup for screen recording: scripts/mac-terminal-setup.md.

Using Claude Desktop

Merge this entry into mcpServers in ~/Library/Application Support/Claude/claude_desktop_config.json (do not replace the file). Use absolute paths: which uv for the command and pwd for the project directory.

{
  "mcpServers": {
    "k8s-assistant": {
      "command": "/opt/homebrew/bin/uv",
      "args": ["--directory", "/ABS/PATH/k8s-mcp-demo", "run", "python", "server/server.py"],
      "env": { "K8S_MCP_KUBECONFIG": "/ABS/PATH/k8s-mcp-demo/kubeconfig/mcp-assistant.kubeconfig" }
    }
  }
}

Configuration

Dependencies are pinned in pyproject.toml / uv.lock (mcp==1.30.0, kubernetes==36.0.3).

Security notes

• No secrets are committed; kubeconfig/ holds a short-lived token and is git-ignored.

• staging is allowed by the server but denied by RBAC. That mismatch is deliberate, to show RBAC is the real boundary.

• This is a demo for a local kind cluster. Review the permissions before pointing it at anything shared.

License

Apache License 2.0. See LICENSE.