kubectl-mcp-server: a Kubernetes MCP server for AI assistants

What kubectl-mcp-server actually solves

The project packages Kubernetes operations as a Model Context Protocol server. The README frames the problem as context switching: instead of leaving an assistant to run kubectl in a terminal, you ask in natural language and the assistant calls a tool the server exposes. The package description in package.json and setup.py states the scope plainly: 270+ tools, 8 resources and 8 prompts for AI assistants.

The intended user is an engineer who already works inside an MCP-capable assistant such as Claude, Cursor, Windsurf or Copilot. The README lists those and says it works with 15+ other AI tools. The server itself is not a dashboard and not a replacement for kubectl; it is an adapter that turns cluster operations into callable tools. If you do not use an MCP client, the project has little to offer beyond its CLI entry points.

How the server is put together

The dependency list is the clearest statement of architecture. setup.py requires fastmcp>=3.0.0b1, with a comment that the alternative is mcp>=1.8.0, plus the official kubernetes Python client, pydantic, fastapi, uvicorn and starlette. That combination points at an MCP server process that can speak over stdio or over a network transport, with the Kubernetes client doing the actual API calls.

The Dockerfile confirms the transport story. It sets TRANSPORT=stdio as the default, with sse, http and streamable-http as alternatives, and binds HOST=0.0.0.0 on PORT=8000 for the network modes. The image installs kubectl at a pinned version, v1.32.0, and Helm v3, so the container has the binaries the tool layer shells out to. An optional extra, mcp-ui-server>=0.5.0, adds interactive dashboards; the README describes these as HTML dashboards with live metrics.

Two entry points are declared: kubectl-mcp and kubectl-mcp-serve. The npm package is a thin wrapper, with bin/cli.js and a postinstall script, so npx works without a Python install step on the user's side.

Installing it and running a first request

The README recommends npx for a zero-install start. This runs the server directly from the npm package:

npx -y kubectl-mcp-server

For a persistent install, the npm package can be installed globally, which the README says gives faster startup:

npm install -g kubectl-mcp-server

If you prefer Python, pip installs the package. The ui extra pulls in the interactive dashboard support:

pip install kubectl-mcp-server
pip install kubectl-mcp-server[ui]

A container build is also provided. The Dockerfile exposes port 8000 and defaults to stdio, so a network transport has to be requested explicitly:

docker build -t kubectl-mcp-server .
docker run --rm -e TRANSPORT=sse -p 8000:8000 kubectl-mcp-server

After installing, the server has to be registered with your assistant. The README has a section titled Quick Setup with Your AI Assistant and another listing all supported assistants; the exact JSON differs per client, so copy the block for your client rather than inventing one. Once connected, a first useful request is the one the README leads with, asking why a pod is crashing. The server returns logs, events and resource analysis through the tools it exposes, and the assistant turns that into an answer. If the assistant sees no tools, the usual cause is that the server process failed to start, which is worth checking before debugging the cluster.

Where the design creates friction

The tool count is the first thing to think about. The package description advertises 270+ tools, and the README's feature list mentions 253 tools in one place and 270+ in the package metadata. A model choosing among hundreds of tools has a real selection problem, and every tool definition consumes context. The README does not document a tool-filtering or allowlist mechanism, so the practical mitigation is to run the server with a narrower kubeconfig context and namespace scope rather than expecting the server to trim its own surface.

The second issue is privilege. The server runs with whatever credentials the kubeconfig gives it, and the README advertises non-destructive mode and secret masking as enterprise features. Those are behaviours you have to verify in your own deployment; the README does not spell out what non-destructive mode blocks. If the server can reach a production cluster with cluster-admin, the assistant inherits that reach. That is a configuration decision, not a project defect, but it is the decision that matters most.

Finally, the Python dependency is pinned to fastmcp>=3.0.0b1, a beta, with a comment noting the fallback to mcp>=1.8.0. Beta dependencies in a server that holds cluster credentials are a maintenance consideration worth naming.

Alternatives and how they differ

The obvious baseline is kubectl itself plus a terminal-capable assistant. That keeps a human in the loop for every command and needs no server, but it also means no structured tool schema, no resource or prompt definitions, and no dashboards. kubectl-mcp-server trades that simplicity for a typed interface the model can call.

A second alternative is a general remote MCP server that exposes shell or HTTP access and lets the model run kubectl through it. That is more flexible and less opinionated, and it puts the burden of Kubernetes-specific behaviour on the prompt. kubectl-mcp-server instead encodes the operations as named tools, which is better for a model that handles Kubernetes poorly and worse if you want to do something the tool set does not cover.

Within the README's own framing, the project positions itself as part of the CNCF Landscape next to Terraform. That is a description of where it sits in the ecosystem, not a claim of functional overlap with Terraform.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-04-08. The most recent release listed is v1.24.0 from 2026-02-20, while package.json and setup.py both carry version 1.25.0, so the published version is ahead of the last tagged release. That gap is normal for projects that tag less often than they publish, but it means the release notes are not a complete changelog for what you install from npm or PyPI.

The licence is MIT, stated in both package.json and setup.py and shown as a badge in the README. MIT is permissive and places few obligations on how you redistribute or modify the code. It says nothing about the Kubernetes cluster you point the server at, and nothing about the assistant vendor's terms. Those are separate questions and the repository does not address them.

Upgrade cost is dominated by the tool surface. Because tools are the interface, a release that adds or renames tools can change what your assistant sees and how it routes a request. The release history shows a security-fix release, v1.23.1, which is the kind of change worth reading before skipping. Pin the version you deploy and read the release notes between pins.

Editorial conclusion

Adopt kubectl-mcp-server if you already drive an MCP-capable assistant and want cluster inspection, Helm work and diagnostics routed through it, and if you are willing to run the server with the RBAC scope you actually need. Do not adopt it if you want a hardened multi-tenant control plane, or if your team cannot review what a generated tool call will do before it runs. Verify first that the transport mode you need matches what the Dockerfile documents, that your assistant is listed in the README's supported set, and that the kubeconfig the server reads points at the cluster you intend to touch.

Frequently asked questions

Official sources

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