kubernetes MCP

The Kubernetes MCP server, maintained under the containers organisation on GitHub, lets an agent work with Kubernetes and OpenShift clusters. It is a native Go program that calls the cluster API directly, so it needs no kubectl or helm. It is Apache-2.0 licensed. Turn on read_only and deny Secrets before you connect it to anything real. We checked it on 31 October 2026.

Quick facts

A note on versioning. The repo tagged v0.0.69 on 23 October and then v0.1.0 and v0.1.1 on 29 October, so it is a fast-moving project in 0.x numbering. Pin a version if you build a workflow on it.

What it does

Most people run Kubernetes through kubectl. An agent with a shell can do the same, but it composes strings, parses text output and carries your full shell rights. This server gives the agent typed tools that call the API server directly, and lets you fence them by toolset, read-only mode and denied resources.

The README leans on this point: it is not a wrapper around the command-line tools. It talks to the API itself, which makes it faster and means nothing else has to be installed. The README does not describe how listings are formatted for the model.

The toolsets

The server groups tools into toolsets and enables only some by default. That is a useful design: a smaller tool list costs less context and exposes less.

The core tools

Paging deserves a mention. Event and list tools take limit and continue arguments, and the server has a max_backend_response_bytes limit, so listing everything in a busy cluster can fail. The tool descriptions tell the model to retry with a smaller limit. That is a sensible guard for large clusters.

Prompts

The server also publishes prompts. One in the core set is cluster-health-check, which does a health assessment of a cluster, optionally limited to a namespace.

A diagnosis walkthrough

This is our suggested flow, built from the tool list. We did not run it. Say a deployment in the shop namespace keeps restarting.

1. Find the symptom. The agent calls pods_list_in_namespace for shop and sees one pod in CrashLoopBackOff.
2. Read the events. events_list with a field selector like involvedObject.name=<pod> shows the warnings: failed probes, an out-of-memory kill or an image pull error. This is the cheapest evidence, so it comes first.
3. Read the logs. pods_log returns the last lines from the crashed container. Ask the agent to quote the first error, not summarise the whole log.
4. Check usage. pods_top shows whether memory is near its limit, which fits an out-of-memory story.
5. Read the spec. resources_get on the Deployment shows the limits, probes and image tag.
6. Propose, do not apply. A good instruction is: "tell me the change, show the YAML, wait for my yes". The write step is resources_create_or_update, and on a read-only setup it simply is not there, which is how you want to learn.

Every step in that list is a read. That is the main argument for starting in read-only mode: most of the value in cluster work with an agent is diagnosis, and diagnosis never needs write rights. When you do turn writes on, do it in a dev namespace, with a Role that allows only the verbs and kinds the change needs, and keep the agent's proposed YAML in a pull request or ticket so a person reviews it before it lands.

One more habit for busy clusters: ask the agent to name the namespace in every tool call it explains. A forgotten namespace argument on a list tool means "all namespaces", which is slow and returns far more than you want in the model's context.

Install it

You need access to a cluster. Run the server by one of three routes:

npx kubernetes-mcp-server@latest --help
uvx kubernetes-mcp-server@latest --help
./kubernetes-mcp-server --help   # a release binary

The README's entry for Claude Desktop and Cursor:

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

It also documents VS Code and VS Code Insiders (a one-click link and a command), Goose CLI, and a dedicated Claude Code guide in its docs folder. For a production-style setup with a dedicated ServiceAccount and read-only access, the README points to a Kubernetes setup guide.

Install it in each agent

Lines below for agents without a documented entry are our adaptation from each agent's MCP docs.

Claude Code

The README refers to a dedicated Claude Code guide. Our adaptation of the stdio entry:

claude mcp add kubernetes -- npx -y kubernetes-mcp-server@latest --config ~/.config/k8s-mcp/config.toml

Write the TOML file first (see below), so the agent starts read-only.

Codex

Our adaptation, in ~/.codex/config.toml:

[mcp_servers.kubernetes]
command = "npx"
args = ["-y", "kubernetes-mcp-server@latest", "--config", "/Users/you/.config/k8s-mcp/config.toml"]

Cursor

The README's mcpServers entry above works in .cursor/mcp.json. Add the --config argument to start with your TOML file.

Antigravity

Our adaptation. Add the stdio entry under mcpServers in ~/.gemini/config/mcp_config.json using command and args. If you run the server in HTTP mode, Antigravity's serverUrl field takes the URL, and Antigravity's docs say it handles OAuth automatically for servers that support dynamic client registration. We did not test that against this server. Gemini CLI is now for Code Assist enterprise customers only.

OpenCode

Our adaptation, in opencode.json:

{
  "mcp": {
    "kubernetes": {
      "type": "local",
      "command": ["npx", "-y", "kubernetes-mcp-server@latest", "--config", "/Users/you/.config/k8s-mcp/config.toml"]
    }
  }
}

Configuration

The README says runtime settings are in TOML (or existing environment variable names), not command-line flags. The CLI takes --version, --config (a file, or - to read stdin in HTTP mode) and --config-dir (a directory of .toml drop-ins).

The README's own example:

log_level = 2
read_only = true
toolsets = ["core", "config", "helm", "kubevirt"]

# Deny access to sensitive resources
[[denied_resources]]
group = ""
version = "v1"
kind = "Secret"

[telemetry]
endpoint = "http://localhost:4317"

What each part does:

• `read_only = true` disables the tools that change things.
• `toolsets` picks which groups load. Leave out helm if the agent should not install charts.
• `denied_resources` blocks a resource kind outright. Denying Secrets is the example, and we would copy it.
• `[telemetry]` is optional OpenTelemetry tracing and metrics.

The configuration reference also covers dynamic reload on SIGHUP, custom prompts and OAuth/OIDC setup for HTTP mode.

Safety: three layers

Kubernetes access is the clearest case for layers, because mistakes are expensive. The server gives you two of them. Kubernetes itself gives you the third.

1. The server's config. read_only, a short toolsets list and denied_resources.
2. A ServiceAccount. Do not use your admin kubeconfig. Make a ServiceAccount with a Role that grants get, list and watch on what the agent needs. The README's Kubernetes guide covers a dedicated ServiceAccount with read-only access.
3. Namespaces and the cluster. Point the agent at a dev or staging cluster, or a namespace, before anything else.

If layer one fails, layers two and three still hold. That is the point of having them.

Security notes

1. Never use cluster-admin. An agent with your admin credentials can delete anything. RBAC is the real control.
2. Deny Secrets. Secrets hold credentials and tokens. Put them in denied_resources.
3. `pods_exec` is a shell. It runs a command inside a container. With write access, an agent can read files, environment variables and mounted secrets in a pod, even when Secrets are denied as an API object. Disable it for anything that matters. The config reference says read_only exposes only tools annotated readOnlyHint=true; it does not say whether pods_exec carries that hint, so check the tool list after you turn it on.
4. Logs and events can leak. Pod logs may contain tokens or personal data, and they pass into the model's context.
5. Logs and resources are untrusted input. A pod's log line or a resource's annotation can contain text written to steer an agent.
6. `resources_create_or_update` is generic. It can create any kind, including RBAC objects and workloads that run privileged containers, unless RBAC says otherwise.
7. Helm installs run chart code paths. helm_install can pull any chart you name. Leave the toolset off unless you need it.
8. HTTP mode. If you run it as a network service, use the OAuth/OIDC options, and do not expose it without them.
9. Multi-cluster by default. With several contexts in your kubeconfig, the tools gain a context argument. Make sure a prod context is not reachable by accident, or trim your kubeconfig for the agent.

Limits and known issues

• Version 0.x. Tools and config keys may change between releases. The README notes that flags moved to TOML and links a migration page.
• Large clusters. Unbounded lists can exceed a response size limit. Use paging.
• Toolset sprawl. Turning every toolset on loads many tools into context. Enable only what you need. The README lists 78 tool entries in total across toolsets.
• Some toolsets need extra components. Kiali, NetObserv, Loki, Prometheus and Tempo toolsets need those services in your cluster.
• Open issues. The repo showed 65 open issues on 31 October 2026.

Alternatives

Other Kubernetes MCP servers exist; the README names a set of "validated Kubernetes ecosystem projects" built on this one. A separate project, Flux159/mcp-server-kubernetes, is not archived and had a push on 26 October 2026. See our MCP server list for more.

Our take

We did not run this server for this page. This comes from the README and the repo data.

We like the design choices: a native client instead of a shell wrapper, toolsets that load only on request, read-only mode, a way to deny whole resource kinds, and a README that points to a ServiceAccount setup. For incident work it fits well. Reading events, logs and pod state is exactly the diagnosis loop an agent can speed up, and none of that needs write access.

The caution is the usual one for any cluster tool. The server's switches are good, but RBAC is the line you can trust, so build the ServiceAccount first. Treat pods_exec and the generic create tool as the sharp edges, and keep a prod context out of the kubeconfig the agent sees.

A short setup checklist

1. Make a ServiceAccount with a read-only Role in one namespace of a dev cluster.
2. Build a kubeconfig that holds only that context.
3. Write a TOML file with read_only = true, a short toolsets list and Secrets denied.
4. Add the server to one agent with --config.
5. Ask for namespaces, then events, then logs of one pod.
6. Add Helm or write access later, in a dev namespace only.

Frequently asked questions

What does the Kubernetes MCP server do?

It lets an agent list, read, create, change and delete Kubernetes and OpenShift resources, read pod logs, exec into pods and manage Helm releases, by talking to the cluster API directly.

Does it need kubectl?

No. It is a Go program that calls the Kubernetes API server itself. It does not wrap kubectl or helm.

How do I make it read-only?

Set read_only = true in its TOML config file. You can also deny whole resource kinds, such as Secrets, with denied_resources.

Which clusters does it use?

Those in your kubeconfig, or the in-cluster config. Multi-cluster support is on by default, and tools gain a context argument when you have several clusters.

Which toolsets are on by default?

Only config and core. Helm, Tekton, KubeVirt, Kiali and observability toolsets are off until you enable them.