kubectl-mcp

The Idea

Give AI agents a real interface to Kubernetes.

LLM assistants are great at explaining kubectl commands and terrible at actually running them safely. kubectl-mcp is an MCP (Model Context Protocol) server that exposes read-only Kubernetes cluster inspection as a set of tools an agent can call — turning "check my cluster" from copy-paste-and-hope into a real conversation.

Roots in an MCP server I prototyped at a Microsoft hackathon. This is the public, pip-installable version, rebuilt for real developers with their own clusters.

Architecture

One protocol, two backends, zero write methods.

The core abstraction is a KubernetesBackend protocol that defines only read methods — list_pods, get_pod, list_recent_events, and friends. Two implementations satisfy it: MockBackend (in-memory, loads a JSON snapshot) and RealBackend (talks to a live cluster via the official Kubernetes Python client).

The MCP server code doesn't know which backend it's talking to — it just calls read methods and formats the results into JSON that the LLM can reason over. Because the protocol has no write methods, there is no code path in this server that can mutate cluster state. Read-only isn't a policy decision that can be forgotten; it's a type-system guarantee.

The Tools

Nine MCP tools, each with a JSON Schema so the LLM gets argument validation for free:

• list_namespaces · list_pods · get_pod
• list_deployments · get_deployment · list_services
• list_recent_events — "what just broke?" in one call
• get_pod_logs — last N lines, read-only, no exec
• find_restarted_pods — high-level triage query

find_restarted_pods is the one that made me feel like I'd built something new. Instead of the LLM chaining three or four raw kubectl-equivalent calls to answer "which pods restarted in the last hour?", one tool call returns exactly the rows the LLM needs, sorted, with the last termination reason attached. Right-sized primitives beat generic ones.

Why a Mock Backend

The mock cluster started as a testing convenience and ended up being the thing that makes this project actually usable. Every Kubernetes tutorial project I'd tried before required you to have a cluster — install minikube, wait for the download, deal with Docker Desktop, hope your laptop has the RAM. Most people bounce before they see the tool work.

With a mock backend as the default, you pip install kubectl-mcp and it works in 30 seconds. The seeded scenario is deliberately messy: healthy pods, a CrashLoopBackOff, an OOMKilled container, real-looking events. When you ask an agent "what's wrong in production?", it has enough to actually answer.

Tradeoffs

• Read-only by construction, not by policy. Simpler to reason about, harder to extend if someone later wants write actions. That's the right tradeoff for an LLM-driven tool — write actions belong in a separate, gated surface.
• No caching. Every tool call hits the backend fresh. For real clusters at scale this would matter; for a personal-tools use case, the simplicity wins.
• Standalone --demo mode to call any tool from the CLI. Non-negotiable for CI smoke tests and for me debugging without spinning up Claude Desktop.

What I Learned

MCP looks like "just JSON-RPC" but the actual design work is in tool shape. The temptation is to expose everything kubectl can do; the payoff is in exposing exactly the right primitives for the agent to reason. find_restarted_pods is one tool call; the equivalent in raw kubectl would be three, plus stitching. That difference is the difference between an agent that feels helpful and one that feels tedious.

→ Source on GitHub  ·  MIT · pip install kubectl-mcp