Securely troubleshoot Kubernetes clusters with Claude Code and MCP

Claude Code can talk directly to your Kubernetes cluster through MCP (Model Context Protocol), a standard that lets AI tools call external systems like kubectl and Helm. The setup takes about five minutes, but the tutorials flooding search results skip the hard part: what happens when your whole team wants this access without scattering high-privilege kubeconfigs and LLM API keys across fifty laptops.

This guide covers the practical setup, compares the major Kubernetes MCP server implementations, and walks through the operational guardrails (RBAC scoping, context pinning, observability) that turn a clever demo into something you'd actually run against production.

Connect Claude Code to your cluster in under five minutes

A Kubernetes MCP server bridges Claude Code and your cluster. Claude sends natural-language requests; the MCP server translates them into kubectl and Helm commands against your current kubeconfig context. The most widely used implementation is containers/kubernetes-mcp-server, which supports pods, deployments, services, logs, Helm charts, and more.

To add it to Claude Code:

claude mcp add kubernetes -- npx kubernetes-mcp-server

That's it. Claude Code can now list pods, describe deployments, tail logs, scale replicas, and apply manifests through conversation. Cursor, Codex, VS Code, and Gemini CLI use the same MCP server with nearly identical configuration.

Prerequisites:

kubectl installed and in your PATH
A valid kubeconfig with at least one context configured
Node.js (for npx) or a pre-built binary
Helm v3 if you want chart operations

Verify your connection first: kubectl get pods. If that works, the MCP server will too.

Choose the Right Kubernetes MCP Server

Not all Kubernetes MCP servers are the same, and the differences matter once you move past a single developer on minikube.

containers/kubernetes-mcp-server: The most feature-complete option. Written in Go, distributed via npm and PyPI. Supports kubectl operations, Helm, non-destructive mode, secrets masking, OpenTelemetry tracing, and a built-in troubleshooting prompt (/k8s-diagnose). Works with Claude Code, Claude Desktop, Cursor, VS Code, Codex, and Gemini CLI.
Flux159/mcp-server-kubernetes: A popular TypeScript alternative with similar kubectl coverage, Helm support, and pod cleanup utilities. Also supports multiple clients.
Blankcut/kubernetes-mcp-server: Oriented toward GitOps workflows. Integrates with ArgoCD and GitLab to correlate Kubernetes state with deployment pipelines.
Claude Code "skills" (e.g., Giant Swarm's kubectl skill): Not MCP servers. They're prompt-level instructions that standardize how Claude generates kubectl commands, enforcing long-form flags, explicit context specification, and JSONPath formatting. Useful as a complement to an MCP server, not a replacement.

Start with containers/kubernetes-mcp-server for breadth, and layer in a skill for command hygiene.

Set up read-only access before giving write permissions

Most tutorials skip this. It's the single most important operational decision when connecting an AI agent to a live cluster.

The containers/kubernetes-mcp-server supports a non-destructive mode that limits operations to reads and creates/updates: no deletes, no scaling, no rollouts. Enable it and start there, especially for production contexts.

Beyond the MCP server's own toggle, the real enforcement layer is Kubernetes RBAC. Create a dedicated ServiceAccount or kubeconfig context with a ClusterRole scoped to the verbs and resources you actually want the AI to touch. The MCP server inherits whatever permissions your kubectl context has. If that context is cluster-admin, so is Claude.

A practical pattern:

Read-only context for production: get, list, describe, logs
Write-capable context for staging: adds apply, scale, patch
Full context for local/dev clusters only

Even if Claude misinterprets a prompt, the blast radius is bounded by Kubernetes RBAC, not by the MCP server's good intentions.

Prevent accidental cross-cluster operations

Context mix-ups are a real production risk. You ask Claude to "delete the stuck pods in staging," and it runs the command against whatever context happens to be active, which might be production.

The Giant Swarm kubectl skill addresses this by requiring explicit --context flags on every command. The containers/kubernetes-mcp-server also lets you pin a specific context at startup. Both approaches are worth adopting.

For teams with multiple clusters, run separate MCP server instances per environment, each locked to a single kubeconfig context. It's slightly more configuration, but it eliminates an entire class of incidents.

Add observability to AI-Driven cluster operations

The containers/kubernetes-mcp-server includes optional OpenTelemetry integration:

export ENABLE_TELEMETRY=true
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
npx kubernetes-mcp-server

This traces every tool call (kubectl_get, kubectl_apply, kubectl_logs) with duration, success/failure, namespace, and context metadata. Export to Jaeger, Grafana Tempo, Datadog, or any OTLP-compatible backend.

But this observability lives inside a single MCP server process on a single developer's machine. It tells you what that instance did. It doesn't tell you what your team did, who ran which operations, or how to attribute cluster changes to a specific engineer when everyone shares the same kubeconfig.

Govern team-wide AI Access to Kubernetes

The harder problem isn't connecting Claude Code to a cluster. It's doing so for 50 engineers without distributing high-privilege kubeconfigs, scattering LLM API keys across laptops, and losing track of who did what.

Aperture by Tailscale addresses the LLM credential side. Instead of distributing Anthropic or OpenAI API keys to every developer running Claude Code or Codex, Aperture acts as a private AI gateway inside your Tailscale network. Engineers authenticate with their existing Tailscale identity: no API keys on laptops, no secrets in dotfiles. Every request is attributed to a real user, with token counts, model usage, session grouping, and full request/response capture for audit.

The Kubernetes credential side still requires per-cluster RBAC and context management. But combining identity-aware AI access (Aperture handles who can talk to the LLM) with scoped kubeconfig contexts (RBAC handles what the LLM can do to the cluster) gives platform teams a governance model that scales across Claude Code, Cursor, Codex, and whatever MCP-compatible client your team picks up next.