mcp-server-kubernetes: a kubectl bridge for MCP clients

The gap between a chat window and a live cluster

Most AI clients cannot see a Kubernetes cluster. They can write YAML, but the loop of applying it, reading the resulting events and correcting the manifest happens outside the conversation, usually by copy-pasting kubectl output back in. mcp-server-kubernetes closes that loop by registering kubectl-shaped tools with any client that speaks the Model Context Protocol. The README frames the project as an "MCP Server that can connect to a Kubernetes cluster and manage it", and the tool list is deliberately close to the CLI: kubectl_get, kubectl_describe, kubectl_create, kubectl_apply, kubectl_delete, kubectl_logs, kubectl_scale, kubectl_patch, kubectl_rollout and kubectl_context, plus kubectl_generic for anything the named tools miss. The audience is platform engineers and developers who already have a working kubeconfig and want an assistant to operate against it, not people looking for a dashboard or a GitOps controller. If you have never run kubectl get pods successfully, this server has nothing to attach to.

How the kubectl wrapper actually routes a request

The package is TypeScript, published as an npm binary named mcp-server-kubernetes that points at dist/index.js, and it runs over stdio by default. A client starts the process, the process reads kubeconfig from ~/.kube/config unless told otherwise, and each tool call becomes a kubectl or Helm invocation against the active context. The dependency list is telling: @kubernetes/client-node sits alongside @modelcontextprotocol/sdk, and there is an OpenTelemetry stack (sdk-node, auto-instrumentations-node, an OTLP gRPC exporter) plus express. So the server is not a pure shell-out; it carries a client library and a tracing path. The README also notes that kubeconfig is loaded from multiple sources in priority order, with environment variables and custom paths documented in ADVANCED_README.md rather than the main file. That split matters when you debug: if the server appears to talk to the wrong cluster, the answer is usually in the advanced document, not the README. Beyond the CRUD verbs, the tool set includes port_forward, a k8s-diagnose troubleshooting prompt, cleanup_pods for Evicted, ContainerStatusUnknown, Completed, Error, ImagePullBackOff and CrashLoopBackOff states, and node_management for cordon, drain and uncordon. Helm support covers install, upgrade and uninstall, with helm_template_apply and helm_template_uninstall offered specifically to bypass authentication issues by templating instead of talking to the cluster's Helm release store.

Installing mcp-server-kubernetes with npx and a first deployment

The prerequisites are explicit: kubectl on PATH, a valid kubeconfig with contexts, a reachable cluster, and Helm v3 if you intend to use the Helm tools. The README suggests confirming the last one with kubectl get pods in a terminal before involving any client. For Claude Code, registration is a single command that writes the MCP entry for you:

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

Codex CLI has an equivalent that registers the server globally in ~/.codex/config.toml:

codex mcp add kubernetes -- npx mcp-server-kubernetes

Clients configured by hand use a JSON block. This is the Claude Desktop and Cursor shape, and the README shows the same command and args pair for both:

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

After restarting the client, the first useful check is the ping tool, which the README lists as the connection verifier. A more concrete first task is asking the assistant to list pods, which should return the same set you saw from the terminal. If the two disagree, the server is reading a different context or a different kubeconfig source, and the priority order described in ADVANCED_README.md is where to look. There is also a packaged route: the project ships as an mcpb extension, installable from Claude Desktop under Settings, Extensions, Browse Extensions, or manually from the .mcpb attached to the latest release. For a chat client without a UI, the README points at mcp-chat:

npx mcp-chat --server "npx mcp-server-kubernetes"

For containerized use, the repository includes a Dockerfile that builds from node:24.2.0-slim, installs kubectl from the Kubernetes v1.32 apt repository, adds gcloud with the gke-gcloud-auth-plugin, awscli and Helm, builds the TypeScript, and runs node dist/index.js as an unprivileged appuser. That image is the honest answer to what the server needs: a shell with cloud CLIs and credentials mounted in.

Where the thin wrapper becomes the wrong tool

Because every tool maps to a cluster-mutating verb, the blast radius equals your kubeconfig's. A context pointing at production gives the assistant delete, patch, scale and drain on production, and the README does not document a confirmation step, a dry-run default, a namespace allowlist or an audit trail. kubectl_generic widens that further: it executes any kubectl command, so the named tools are conveniences rather than a restricted surface. The k8s-diagnose prompt is a troubleshooting flow, not a safety mechanism. There is a second, quieter limitation. The server is a local process reading local credentials, so it does not solve multi-user access, and nothing in the README describes per-user authorization. If you need a shared, policy-enforced interface to a cluster, this is the wrong layer; the right layer is whatever already enforces RBAC and admission policy in front of the API server. The Helm template tools exist precisely because authentication to the cluster's Helm store can fail, which is a useful escape hatch and also a sign that the Helm path is not always clean.

Alternatives: raw kubectl, and client-native Kubernetes plugins

The obvious alternative is kubectl itself. It is already installed, already respects your kubeconfig, and already has the flags you trust. The difference is the interface: kubectl returns text a human reads, while this server returns results an MCP client can reason over and chain into further calls, which is what makes the diagnose-then-fix loop possible without copy-paste. The second alternative is a Kubernetes plugin built into a specific client rather than a standalone MCP server. That trades portability for integration: a client-native plugin only works in that client, whereas this project registers the same stdio command in Claude Code, Codex, Claude Desktop, Cursor and VS Code, and can also be driven from mcp-chat or run from the Docker image. If you only ever use one editor, the plugin route has fewer moving parts. If you move between clients, the MCP server is the one registration that follows you, at the cost of being a process you have to keep current.

Maintenance, upgrade cost and the MIT licence

The repository is not archived, and the last push was on 2026-08-31, the same day v4.1.6 was released, with v4.1.5 earlier that day and v4.1.4 on 2026-08-08. Releases cluster, so upgrading means reading a changelog rather than tracking a slow drift, and the package version in package.json (4.1.7) sits ahead of the newest release listed, which is normal for a repository between a release and the next publish. Upgrade cost is mostly environmental: the server shells out to kubectl and Helm, so a cluster-side API change or a kubectl bump can alter behaviour without any change to this package. The Dockerfile pins kubectl to the v1.32 apt repository and the base image to node:24.2.0-slim, so a containerized deployment inherits those pins and needs a rebuild to move. Node 18 or newer is required by the engines field. The licence is MIT, which permits commercial and private use and modification; the repository also carries a CITATION.cff, a SECURITY.md and a CONTRIBUTING.md, so there is a stated process for reporting issues. None of that is legal advice, and the licence file is the authority if you need to redistribute the code.

Editorial conclusion

Adopt mcp-server-kubernetes if you already drive a cluster with kubectl and want an MCP-capable assistant to run the same verbs against the same kubeconfig, including through the bundled Helm chart. Do not adopt it as a policy boundary: the README does not document an approval gate, an audit log or a dry-run default, so anyone who can reach the server can reach whatever the kubeconfig permits. Before wiring it into a shared client, run kubectl get pods by hand to confirm which context is active, then check whether that context is the one you want an assistant to mutate.

Frequently asked questions

Official sources

1. Flux159/mcp-server-kubernetes on GitHub
2. License: MIT
3. Project website
4. README
5. Releases