kaka-milan-22/kops

Read-only kubectl helper exposed to Claude Code via MCP. Six tools, all strictly read-only — verbs (get, describe, logs) are hardcoded; user input only fills argument values, never the verb itself.
| Tool | What it does |
|------|------|
| k8s_get | List/fetch resources, returns summarized key fields per kind |
| k8s_describe | kubectl describe text output for one resource |
| k8s_logs | Pod logs with tail / since / previous flags |
| k8s_events | Recent events filtered by namespace / kind / name |
| k8s_triage | ⭐ One-shot cluster health scan — start here for diagnostics |
| k8s_inventory | ⭐ One-shot comprehensive snapshot — start here for documentation / audits |
Why
kubectl over Bash gives Claude text tables that need re-parsing every turn. Wrapping it as MCP returns **structured JSON** Claude can reason over directly — fewer tokens, fewer parse errors, and built-in safety boundaries (read-only verbs, name validation, output size caps).
Two aggregator tools (k8s_triage, k8s_inventory) compress common multi-step queries into single round-trips:
- k8s_triage — "what's broken?" → 4 concurrent kubectl calls, returns problem pods + warning events + unhealthy nodes + stale deployments
- k8s_inventory — "show me everything" → 14+ concurrent kubectl calls, returns cluster-wide snapshot grouped by namespace. Replaces ~50 individual k8s_get calls (~6× faster end-to-end for cluster docs).
Install
Requires uv and kubectl in your PATH.
> The commands below use /path/to/kops for the absolute path of this clone —
> replace it with your actual path (e.g. the output of pwd run from inside the
> cloned directory). uv --directory needs an absolute path.
Smoke test (no cluster needed)
MCP requires a handshake (initialize → notifications/initialized) before any business request, so a bare tools/list over stdin is rejected with Received request before initialization was complete. Feed all three messages in order:
Expect: an initialize response, then a tools/list response listing the **6 tools** with input schemas. (The notification has no id and produces no reply.)
Visual debug with MCP Inspector
For interactive debugging, skip the raw stdio dance and use the official tools — they handle the handshake for you:
Open the URL each prints, click a tool, exercise its parameters.
Register with Claude Code
Or manually in ~/.claude.json under mcpServers:
Reload Claude Code (or open a new session). Tools surface as mcp__kops__k8s_get, mcp__kops__k8s_triage, mcp__kops__k8s_inventory, etc.
Multi-cluster (kubeconfig isolation)
To talk to a foreign cluster without polluting ~/.kube/config, register a separate server entry with its own KUBECONFIG:
Tools then surface as mcp__kops_qa__k8s_triage etc, fully isolated.
End-to-end smoke (with a kind cluster)
Then in Claude Code, ask: "this cluster has problems, what's wrong?"
Expected: Claude calls mcp__kops__k8s_triage first, sees the broken pod in ImagePullBackOff, then k8s_describe for root cause.
For a documentation example, ask: "give me a full report of this cluster".
Expected: Claude calls mcp__kops__k8s_inventory once and assembles a structured markdown report covering nodes, namespaces, workloads, services, exposure surface, and configuration counts.