kubectl-mcp

An MCP (Model Context Protocol) server that lets AI agents inspect Kubernetes clusters in plain English — ask "which pods restarted in the last hour?" and get a real answer.

Built by Teresa Tran.

Why

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

• Read-only by design. No apply, no delete, no exec. The server only ever inspects.

• Mock mode by default. Ships with a seeded fake cluster so you can try it in 30 seconds without a real cluster.

• Real mode when you're ready. Point it at your KUBECONFIG and it queries a live cluster via the official Kubernetes Python client.

Related MCP server: Kubernetes MCP Server

Install

pip install kubectl-mcp                # mock mode (default)
pip install "kubectl-mcp[real]"        # + real-cluster support (kubernetes client)

Or from source:

git clone https://github.com/teresa-tran/kubectl-mcp.git
cd kubectl-mcp
pip install -e ".[real,dev]"

Run it standalone (sanity check)

kubectl-mcp --help                     # show flags
kubectl-mcp --list-tools               # print every MCP tool + its schema
kubectl-mcp --demo list_pods           # run a tool once against the mock cluster
kubectl-mcp --demo find_restarted_pods --arg since_minutes=120

Wire it into an MCP client

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (mac) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp"
    }
  }
}

For real-cluster mode:

{
  "mcpServers": {
    "kubectl": {
      "command": "kubectl-mcp",
      "env": {
        "KUBECTL_MCP_MODE": "real",
        "KUBECONFIG": "/Users/you/.kube/config"
      }
    }
  }
}

Restart Claude Desktop. You should now be able to ask "list pods in the production namespace" and get a real answer.

Other MCP-compatible clients

Any client that speaks stdio MCP (Cursor, Cline, Continue, custom agents) works the same way — point it at the kubectl-mcp binary.

Tools exposed

Every tool has a JSON Schema — LLMs get proper argument validation for free.

Configuration

Environment variables:

The mock cluster

The default mock cluster ships in src/kubectl_mcp/mock_data.json and includes:

• 3 namespaces: default, production, staging

• ~15 pods spanning healthy, crashlooping, and recently-restarted states

• Deployments, services, and a stream of recent events

• Some pods have restart counts > 0 so find_restarted_pods returns real results

You can override it by setting KUBECTL_MCP_MOCK_DATA=/path/to/your.json if you want to demo a specific scenario.

Design notes

• Read-only by construction. The KubernetesBackend protocol only defines read methods. There's no code path that can mutate cluster state — even in real mode.

• Backend is swappable. MockBackend and RealBackend implement the same protocol. Adding a third (e.g., a cached snapshot) is one file.

• Errors are exceptions, not silent nulls. ResourceNotFound, NamespaceNotFound, etc., propagate as McpError with helpful messages so the agent can course-correct.

• stdio transport. All MCP tool calls are JSON-RPC over stdio, matching the MCP spec exactly.

Development

pip install -e ".[real,dev]"
pytest                                 # run tests
ruff check src tests                   # lint
kubectl-mcp --demo list_pods --arg namespace=production   # smoke test

Roadmap

• Mock backend with seeded data

• Real backend via kubernetes python client

• Read-only tool surface

• Standalone --demo mode for CI/smoke tests

• Multi-cluster support (--context flag)

• Metrics tools (CPU/memory via metrics.k8s.io)

• Optional caching layer for high-frequency queries

License

MIT © 2026 Teresa Tran