Kubernetes MCP Server

A production-ready Model Context Protocol server that gives AI agents and LLM applications full visibility into — and (opt-in) control over — a Kubernetes cluster: manage resources, troubleshoot problems, and debug applications. 37 read-only tools by default; 13 mutating with --allow-writes, 4 destructive with --allow-destructive, and 4 debug tools with --allow-debug (58 total when every flag is set).

Status: production-ready

All phases complete and verified against a live cluster (including a full create→verify→delete lifecycle). 11/11 packages have automated unit tests; the security regression suite asserts tools are unreachable per mode; CI (lint/vet/test), kind e2e (multi-version), and goreleaser release pipelines are wired.

Written in Go using the official MCP Go SDK and client-go.

Why

Point an MCP-aware client (Claude Desktop, Cursor, opencode, Claude Code, …) at this server and the agent can: read logs, diagnose a crashing pod, inspect events, describe any resource, list workloads/services/secrets, and — when you explicitly unlock it — apply manifests, scale deployments, drain nodes, exec into containers, and port-forward.

Safe by default. The server boots read-only. Mutating, destructive, and debug tools are not even registered unless you pass the corresponding flag.

Features

• 37 read tools across core, workloads, troubleshoot, network, and configstore, plus 13 mutating, 4 destructive, and 4 debug tools (58 total with all flags). list_pods, get_logs, describe (any GVK incl. CRDs), list_events, top_pods/top_nodes, rollout_status/rollout_history, and an automated diagnose_pod/diagnose_node engine (CrashLoopBackOff, ImagePullBackOff, OOMKilled, probe failures, scheduling/PVC issues, node pressure).
• Generic describe over the dynamic client — works for any built-in or CRD.
• Secrets masked with change-detection hashes; reveal requires an explicit flag and per-call opt-in.
• Bounded output (configurable truncation) to protect context windows.
• Audit logging of every tool call (read/write/destructive classified).
• Two transports: stdio (local agents) and streamable http (shared).
• Blast-radius controls: namespace allowlists, tool-category toggles, privileged-target guard, dry-run defaults.

Install

Homebrew (macOS & Linux):

brew install --cask langazov/tap/k8s-mcp-server

Pre-built binaries, the Docker image, go install, building from source, and in-cluster deployment are covered in the Installation guide.

Prefer a guided setup? Run the interactive wizard — it picks your AI client and configures the start options for you:

./scripts/install-wizard.sh

Quick start (stdio)

./k8s-mcp-server --kubeconfig ~/.kube/config

Logs go to stderr; MCP traffic flows over stdin/stdout. Read-only by default.

Unlock more power

# Read + mutating tools (scale, apply, restart, configmaps, ...)
./k8s-mcp-server --allow-writes

# + destructive tools (delete, drain, cordon)
./k8s-mcp-server --allow-destructive

# + debug tools (exec, ephemeral containers, port-forward, debug pods)
./k8s-mcp-server --allow-debug

# Restrict to specific namespaces
./k8s-mcp-server --namespace team-a --namespace team-b

Client configuration

Claude Desktop / Claude Code (claude_desktop_config.json)

{
  "mcpServers": {
    "kubernetes": {
      "command": "/path/to/k8s-mcp-server",
      "args": ["--kubeconfig", "/Users/you/.kube/config"]
    }
  }
}

opencode

{
  "mcp": {
    "kubernetes": {
      "type": "local",
      "command": ["k8s-mcp-server", "--kubeconfig", "~/.kube/config"]
    }
  }
}

Cursor

Add a "local" MCP server pointin

... View full README on GitHub