Kubernetes MCP Server: The Complete Guide

One-sentence definition

A Kubernetes MCP server is a program that exposes cluster operations — listing pods, reading logs, scaling deployments, applying manifests — as Model Context Protocol tools, so any MCP client (Claude Desktop, Claude Code, Cursor, VS Code) can drive your cluster through structured tool calls instead of a human at a terminal.

The agent asks a question in English — “why is the checkout pod restarting?” — and the server translates that into real API reads: get the pod, fetch its events, pull the last 200 log lines, describe the deployment. You read the answer; the agent did the typing.

Why it exists

Cluster debugging is a context-gathering grind. A pod is crash-looping, so you kubectl describe pod, then kubectl logs --previous, then kubectl get events, then kubectl describe deployment, mentally stitching the output into a story. Each command is trivial; the cost is the stitching and the back-and-forth.

Before MCP, wiring an LLM into that loop meant writing a bespoke function-calling shim per tool, per client. MCP standardizes the wire format, so one server speaks to every compliant client. The Kubernetes MCP server is that loop, automated: the agent runs the gather steps in one turn and hands you a correlated answer. That is the entire value proposition — and also, exactly, where the danger lives, because the same channel that reads can also write.

The named pieces

Four parts show up in every Kubernetes MCP setup. Get these straight and the rest of the post lands.

client → MCP server → (kubeconfig/SA) → API server → cluster

Read that chain left to right and the security story writes itself: nothing in the client or the server is a real boundary. The API server’s RBAC, scoped to that one credential, is the only thing standing between “the agent read a log” and “the agent deleted a namespace.”

The main implementations (they are not the same)

“Kubernetes MCP server” is a category, not a product. Several mature, open-source servers exist, and they differ in real ways. Here are the three most cited, plus the cloud-vendor entries you’ll bump into.

containers/kubernetes-mcp-server

Maintained under the containers GitHub org (the same community behind Podman), this is the most feature-broad of the open implementations. Its README is explicit that it is not a kubectl wrapper: “a Go-based native implementation that interacts directly with the Kubernetes API server.” Red Hat Developer describes it as a “single binary with no external dependencies, such as kubectl, Helm, Node.js, or Python.” It targets both Kubernetes and OpenShift, ships toolsets for Helm and Tekton, supports multi-cluster by default, and is Apache-2.0 licensed. Opinionated takeaway: if you want one server that covers the widest surface, this is the default pick.

feiskyer/mcp-kubernetes-server

Maintained by feiskyer, this one openly does lean on the CLIs — its README says it “translates natural language requests into kubectl commands or direct Kubernetes API calls.” That means you need kubectl and (optionally) helm on the host or in its Docker image. The upside is granular kill switches: --disable-kubectl, --disable-helm, --disable-write, and --disable-delete. Apache-2.0. Takeaway: pick it if you want CLI-faithful behavior and fine-grained command gating.

strowk/mcp-k8s-go

Maintained by strowk, a lighter native-Go server focused on the core loop: list contexts and namespaces, list/get/create/modify resources, read pod logs, fetch events and node info. It is the easiest to install casually — npx @strowk/mcp-k8s, Homebrew, Docker, or go install — and ships a --readonly flag that “disables any tool which can write changes to the cluster.” Takeaway: the right starting point if you want a small footprint and read-only by default.

Cloud-vendor servers (AKS, and others)

The managed-Kubernetes vendors ship their own. Azure’s aks-mcp is open-source and notable for one thing this guide cares about: it defaults to read-only access and only does writes if you pass --access-level readwrite or admin. Microsoft’s docs are blunt that “all actions performed through the AKS MCP server are constrained by Kubernetes Role-Based Access Control (RBAC) and Azure RBAC.” If you’re on a managed platform, check whether your provider has a first-party server before reaching for a generic one.

Sourced from each project’s README, June 2026. Flags and feature sets change — confirm against the current README before you rely on a kill switch.

Smallest end-to-end example

The fastest way to feel what this does, using the containers implementation, run locally and read-only. First, register it with Claude Code against your current kubeconfig:

# native Go binary, read-only, your current kube context
npx -y kubernetes-mcp-server@latest --read-only

For Claude Desktop, the README’s config block is the canonical shape (add --read-only to the args for safety):

{
  "mcpServers": {
    "kubernetes": {
      "command": "npx",
      "args": ["-y", "kubernetes-mcp-server@latest", "--read-only"]
    }
  }
}

Restart the client, then ask the agent a real question:

You: Which pods in the "payments" namespace are not Running, and why?

Agent → pods_list(namespace: "payments")
Agent → events_list(namespace: "payments")
Agent → pods_log(name: "checkout-7d9f", namespace: "payments")

Agent: checkout-7d9f is in CrashLoopBackOff. Its last log line is
"FATAL: DATABASE_URL is empty". The deployment references a secret
key "db-url" that doesn't exist in the "payments" namespace.

Three reads, one correlated answer, no terminal juggling. Note that with --read-only the agent cannot fix it — it can only tell you what’s wrong. That’s the trade you want for a first run.

Install the catalog server

The MCP.Directory catalog lists a Kubernetes server that bridges kubectl for real-time resource management inside a conversation. Use the panel below for the exact one-click button, copy command, or JSON snippet per client — it pulls configs straight from our catalog, so it stays in sync.

One-line install · Kubernetes

Open server page

Install

Cursor

One-click install

VS Code

One-click install

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

This is one option, not the only one. If you want the native-Go breadth of the containers implementation, the multi-toolset feiskyer server, or the small-footprint strowk server, install those directly from their repos (links in Sources). Whichever you pick, the first install should be read-only against a non-production cluster. Browse the full cloud infrastructure category for related servers, or the whole server directory.

What the tools actually cover

Tool names vary per server, but the coverage clusters into four buckets. Using the containers implementation’s tool set as the reference:

• Inspect (read): pods_list, pods_get, pods_log, events_list, resources_list, resources_get, nodes_top, configuration_view. This is the bucket you can hand an agent with low anxiety.
• Operate (write): resources_create_or_update, resources_scale, pods_run, resources_delete, pods_delete. Every entry here is a mutation. Gate them.
• Execute (escalation): pods_exec runs commands inside a container. This is the most powerful and most dangerous tool in the set — a shell in your workload is a shell in your workload.
• Extensions: Helm (helm_install, helm_list), Tekton pipeline triggers, and KubeVirt/Kiali toolsets in the containers server. Useful, and each one widens the blast radius another notch.

The takeaway senior engineers internalize fast: the read bucket is a productivity win with little downside; the operate and execute buckets are where you decide how much trust the agent earns.

Transports and how it reads your cluster

Two questions decide your setup: how the client talks to the server (transport), and how the server talks to the cluster (credential).

Transport. stdio is the default — the client launches the server as a subprocess on your laptop. The containers and feiskyer servers also offer Streamable HTTP (path /mcp) and SSE (path /sse) via a --port flag, which is how you run the server centrally for a team instead of on every developer’s machine.

Credential. Locally, the server reads your kubeconfig — the containers server takes a --kubeconfig flag or auto-detects the default path; feiskyer’s reads the KUBECONFIG environment variable. In a cluster, it uses the in-cluster service account. This is the single most important line in the whole setup, so it gets its own section next.

The RBAC problem nobody can opt out of

Microsoft states the principle cleanly for its AKS server: “all actions performed through the AKS MCP server are constrained by Kubernetes Role-Based Access Control (RBAC) and Azure RBAC” and “by default, the AKS MCP server inherits the user’s permissions.” Red Hat’s guidance for the containers server is equally explicit: “run the MCP server with a dedicated service account” and “optionally, start the server using the --read-only configuration option (as a safeguard if RBAC isn’t already tightly scoped).”

Translate that into a checklist you can actually run:

1. Never use your admin context. Create a dedicated service account (a cluster-reader ClusterRole binding is a sane start) and point the server at that.
2. Default to read-only. Turn on --read-only (or --readonly, or --disable-write — the flag name differs per server). Earn write access later, per cluster, deliberately.
3. RBAC is the real wall, the flag is a seatbelt. A --read-only flag is a config toggle in the server; RBAC is enforced by the API server. Use both, but trust RBAC.
4. Keep prod off the agent until you’ve watched it. Run against staging, read the tool traces, and only then decide whether prod gets read access — and whether write ever does.
5. Mind prompt injection. If the agent reads logs or events that contain attacker-controlled text, that text can try to steer the next tool call. Read-only limits the damage of a steered call to “it read something it shouldn’t,” not “it deleted something.”

What we got wrong

Two assumptions burned us when we first wired one of these up.

We assumed “read-only mode” meant “safe.” It doesn’t — it means “no writes.” A read-only agent pointed at a kubeconfig with broad read scope can still pull every secret in the cluster through resources_get on Secret objects. Read access to Secrets is sensitive. The fix was RBAC that scopes reads too, not just writes.

We assumed all “Kubernetes MCP servers” were the same project. They’re not. We followed a blog’s install steps for one server while reading the README of a different one, and spent twenty minutes confused about why a flag didn’t exist. The containers, feiskyer, and strowk servers have different names, different flags, and different tool names. Pick one, bookmark its README, and ignore the rest.

Common mistakes

Who this is for (and who it’s not)

Use a Kubernetes MCP server if you:

• Spend real time on kubectl describe / logs / get events debugging loops and want them correlated in one turn.
• Can scope a dedicated read-only service account and are disciplined about RBAC.
• Work mostly in staging/dev clusters where a wrong tool call is recoverable.

Skip it (for now) if you:

• Would only ever point it at a production admin context — the risk outweighs the convenience.
• Have a compliance posture that forbids automated agents touching the control plane.
• Want write automation but haven’t yet built the RBAC, audit logging, and review process to make it accountable.

Community signal

Interest is real and the framing is consistently cautious. On Hacker News, the “Show HN: I made an open source Kubernetes MCP Server to talk with K8s in English” thread (March 2025) is one of several Show HN launches in this space, and a recurring theme across the K8s MCP discussions is the “when does an MCP server beat a plain CLI?” question — the consensus leans toward read/debug being the safe sweet spot, with write operations treated warily.

The vendor docs reinforce the same posture. Microsoft ships its AKS MCP server read-only by default, requiring an explicit --access-level readwrite to mutate anything. Red Hat’s walkthrough for the containers server leads with the dedicated service account and the --read-only safeguard rather than with capability flexing. When the cloud vendors and the platform maintainers all default to read-only, that is the community signal: the tech is useful, and the careful default is the endorsed one.

We looked for a first-party maintainer launch tweet to embed here and could not verify one we were confident attributing, so we’re citing the primary docs and the HN thread directly instead of paraphrasing a tweet we can’t stand behind.

The verdict

Frequently asked questions

Glossary

• MCP (Model Context Protocol): the JSON-RPC wire format that lets any LLM client call any tool server. See our MCP primer.
• MCP server: a program exposing tools over MCP — here, Kubernetes operations.
• kubeconfig: the file holding cluster endpoints and credentials; defines what the server can reach.
• Service account: a non-human cluster identity; the recommended credential for an MCP server.
• RBAC: Role-Based Access Control — the API server’s permission system; your only hard boundary.
• ClusterRole / binding: RBAC objects that grant a set of verbs on resources to an identity.
• stdio transport: client runs the server as a local subprocess over standard in/out — the default.
• Streamable HTTP / SSE: network transports for running the server centrally for a team.
• Read-only mode: a server flag that blocks write tools; a seatbelt, not the wall.
• pods_exec: a tool that runs commands inside a container — the highest-risk capability.
• Multi-cluster: the server can target more than one cluster, usually via a context argument.
• Prompt injection: attacker text in data the agent reads (logs, events) that tries to steer its next action.

Sources & links

Primary sources

• containers/kubernetes-mcp-server (native Go, Apache-2.0): github.com/containers/kubernetes-mcp-server
• feiskyer/mcp-kubernetes-server (kubectl + API, Apache-2.0): github.com/feiskyer/mcp-kubernetes-server
• strowk/mcp-k8s-go (native Go, --readonly flag): github.com/strowk/mcp-k8s-go

Documentation

• Red Hat Developer — “Kubernetes MCP server: AI-powered cluster management”: developers.redhat.com
• Microsoft Learn — “Connect your AKS cluster to AI agents using the MCP server” (RBAC & read-only default): learn.microsoft.com

Community

• Hacker News — Show HN: open source Kubernetes MCP server: news.ycombinator.com/item?id=43486174

Internal

• Kubernetes server in our catalog
• Cloud infrastructure MCP servers
• What is the Model Context Protocol?
• Browse all MCP servers