mcp-server-kubernetes: kubectl and Helm behind an MCP tool surface
MCP Server for kubernetes management commands
At a glance
- What is it?
- Flux159/mcp-server-kubernetes wraps kubectl, Helm and port forwarding into MCP tools that an assistant can call. It is a thin, MIT-licensed TypeScript bridge, and its safety story depends almost entirely on the kubeconfig you point it at.
- Who is it for?
- Adopt it if you already drive a cluster from a terminal and want an assistant to run kubectl_get, kubectl_describe, kubectl_logs and helm operations without leaving the chat. Do not adopt it if your cluster holds production workloads that no human reviews before apply, delete or node_management runs, or if you need a policy layer between the model and the API server.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 2 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap it fills between a chat window and a live cluster
An assistant that cannot reach a cluster can only write YAML and guess. This project exists to close that gap: it is an MCP server that connects to a Kubernetes cluster and exposes management operations as callable tools. The README states it "can connect to a Kubernetes cluster and manage it" and that it supports loading kubeconfig from multiple sources in priority order. The audience is narrower than "Kubernetes users". It is engineers who already have a working kubectl setup, who run an MCP-capable client such as Claude Code, Codex, Cursor or VS Code with an MCP extension, and who want the assistant to read cluster state rather than hallucinate it. The tool list is the real product: kubectl_get, kubectl_describe, kubectl_logs, kubectl_apply, kubectl_delete, kubectl_scale, kubectl_patch, kubectl_rollout, kubectl_generic, plus Helm install, upgrade and uninstall, port_forward, cleanup_pods and node_management. If you only want to read manifests from a repository, you do not need this. If you want the model to see what is actually running, you do.
A kubectl and Helm wrapper, not a client library
The architecture is deliberately unambitious, and that is the interesting design choice. The prerequisites are kubectl on PATH, a valid kubeconfig with contexts, cluster access, and Helm v3 on PATH (optional unless you use Helm operations). The README notes Helm v3 requires no Tiller. That means the server is not reimplementing the Kubernetes API in TypeScript; it is executing the CLI tools you already trust and returning their results to the model. Credential resolution, exec plugins, cloud provider auth and context switching stay in kubectl's hands. The README says the server loads kubeconfig from ~/.kube/config by default, with additional authentication options such as environment variables and custom paths documented in ADVANCED_README.md. The README also states the server "will automatically connect to your current kubectl context". Two Helm features are worth noting because they reveal the wrapper's limits: helm_template_apply and helm_template_uninstall exist specifically to "bypass authentication issues" by rendering templates rather than letting Helm talk to the cluster directly. That is a workaround for environments where Helm's auth path fails, and it changes what Helm can track. The k8s-diagnose prompt is the other non-tool asset, described as guiding a systematic troubleshooting flow.
Install commands per client, and the one prerequisite that matters
Every documented path starts with the same check. The README says to run kubectl get pods in a terminal to confirm you can reach the cluster without credential issues. Do that first. For Claude Code, the command is claude mcp add kubernetes -- npx mcp-server-kubernetes. For Codex, it is codex mcp add kubernetes -- npx mcp-server-kubernetes, which the README says registers the server globally in ~/.codex/config.toml and makes its tools available in all Codex sessions. For Claude Desktop, Cursor and VS Code extensions, the configuration is the same JSON block: an mcpServers object with a kubernetes entry whose command is npx and args is ["mcp-server-kubernetes"]. The VS Code variant in the README adds a description field. mcp-server-kubernetes is also distributed as an mcpb extension, installed from Settings, Extensions, Browse Extensions in Claude Desktop, or manually from a release artifact. To exercise it without a full client, the README shows npx mcp-chat --server "npx mcp-server-kubernetes", or pointing mcp-chat at an existing Claude Desktop config with --config and the platform-specific path. Note the global registration on Codex: every session gets the tools, not just the one you intended.
kubectl_generic is the escape hatch and the sharpest edge
The tool list contains a deliberate hole in its own abstraction. kubectl_generic executes any kubectl command. That is useful, because no fixed tool set covers every resource type or flag, and the README also ships list_api_resources and explain_resource for discovery. It is also the point where the wrapper stops constraining anything. A model that can call kubectl_generic can reach every verb kubectl supports, and kubectl_delete and node_management (cordoning, draining, uncordoning) are already in the named set. The README does not describe an approval step, a namespace allowlist, a dry-run default, or a read-only mode. It does describe cleanup_pods, which deletes pods in Evicted, ContainerStatusUnknown, Completed, Error, ImagePullBackOff and CrashLoopBackOff states; that is a bulk delete driven by a state classifier, not by a human reading a list. The practical consequence is that the blast radius equals the permissions in the kubeconfig the server loads. If that file points at a context with cluster-admin, the model inherits cluster-admin. The README's own verification step, kubectl get pods, tells you which context you are on; it does not tell you how much that context can do. Run kubectl auth can-i --list against the same context before you wire this into a client, and prefer a kubeconfig whose context is scoped to the namespace you are willing to let an assistant mutate.
Where this is the wrong tool, and what to use instead
This server is a single-user, local, CLI-backed bridge. It has no server-side audit log, no policy engine, no multi-tenant credential brokering and no reconciliation loop. If you need any of those, the difference in approach matters more than any feature comparison. A GitOps controller such as Argo CD or Flux takes the opposite stance: the cluster state is derived from a Git repository, changes arrive as commits, and drift is reconciled continuously. With mcp-server-kubernetes, changes arrive as tool calls in a chat session and nothing records them unless kubectl or your cluster's audit logging does. That makes the GitOps path the right one for production fleets where every change should be reviewable and revertible. The MCP server is the right one for the exploratory phase: asking what is crashlooping, reading logs from a failing pod, describing a resource, port forwarding to debug locally, or explaining an API resource you have not used before. Those are read-heavy, short-lived, interactive tasks where a commit-and-reconcile cycle is too slow. Choosing between them is not a maturity question. It is a question of whether the change should exist as a diff afterward.
Maintenance cost, release cadence and the MIT licence
The repository is TypeScript and MIT-licensed, and the recent release list shows v4.1.6, v4.1.5 and v4.1.4 within roughly three weeks, with the latest push on 2026-08-31. That cadence cuts both ways: fixes arrive quickly, and a pinned version is worth considering if you script the install rather than relying on npx resolving the latest tag each run. Because the server shells out to kubectl and Helm, your upgrade surface includes three moving parts. A kubectl or Helm major change can alter output that the tools parse. An MCP client update can change how tools are registered or how the server is launched. And the server itself ships new tools, as the README shows with kubectl_scale replacing the legacy scale_deployment. That last example is the concrete migration cost: if you or your team wrote prompts or scripts around scale_deployment, they need updating. The MIT licence is permissive and imposes no copyleft obligation on your own code, but it also means no warranty and no support commitment from the maintainer. This is not legal advice; if you redistribute the server inside a product, read the licence text and your own compliance requirements.
What to verify before you point it at anything that matters
Three checks, all cheap, all before the first apply. First, kubectl config current-context and kubectl get pods, to confirm which cluster and namespace the server will inherit, since the README says it connects to your current kubectl context automatically. Second, kubectl auth can-i --list in that context, to see whether the model is about to receive delete and drain rights it should not have. Third, decide explicitly whether kubectl_generic stays in scope for your setup, because it is the tool that makes the rest of the tool list advisory rather than enforcing. If your client supports disabling individual tools, that is the cleanest lever; the README does not document one. For Helm users, note the template-based apply and uninstall paths exist to work around authentication failures, and confirm whether releases managed that way still appear in helm list the way your team expects. Start with reads: kubectl_get, kubectl_describe, kubectl_logs, explain_resource. Add writes only after you have watched what the assistant does with them on a disposable cluster.
Editorial conclusion
Adopt it if you already drive a cluster from a terminal and want an assistant to run kubectl_get, kubectl_describe, kubectl_logs and helm operations without leaving the chat. Do not adopt it if your cluster holds production workloads that no human reviews before apply, delete or node_management runs, or if you need a policy layer between the model and the API server. Before installing, verify with kubectl get pods which context and namespace your kubeconfig resolves to, and check whether the server's own context selection follows your current-context or overrides it.
Community notes