A morning cluster health note
Prompt
Every weekday at 8:30, list the pods in my production namespace that are not in Running state, add the restart count and the last few log lines for each, and write it all to cluster-morning.md.
Verified MCP server: Kubernetes
The Kubernetes MCP server, enumerated live on a real Mac.
- Tools enumerated2026-08-03macOS 26.3.1
- Packagemcp-server-kubernetes 4.1.2
- Self-reportedkubernetes 4.1.2
- MCP protocol2025-06-18
- RuntimeNode v24.18.0
The tool list below is a live capture from the running server; an authenticated tool call is still pending credentials.
The short answer
Last verified 2026-08-03
The Kubernetes MCP server hands an AI assistant the kubectl surface of your cluster: list and describe resources, read pod logs, scale a deployment, apply a manifest, cordon a node, run Helm. Neither of the two leading packages comes from the Kubernetes project itself, and the one with the most downloads is mcp-server-kubernetes, which runs on your own Mac over stdio and drives the kubectl binary you already have. There is no account and no API key anywhere in it. What it does need is a kubeconfig pointing at a cluster you can already reach, and that is the line this page stops at: we ran the server, spoke the protocol to it, and enumerated all 23 tools it exposes, but the only context on our test Mac pointed at a Docker Desktop endpoint with Kubernetes switched off, so every cluster-touching call came back with a connection error. Those errors are printed below, word for word, next to the tool table. Two things are worth knowing before you start. kubectl has to be installed separately and on your PATH, because this server shells out to it, and the default tool set is full read and write, deletes included. [1][2][3][5][8]
Verification
How this MCP server was verified.
Method
We spawned the server with npx over stdio, completed the MCP initialize handshake, and called tools/list: the 23 tools below are that response, word for word. We then made real tool calls. Two of them answered, because neither touches a cluster: ping, and kubectl_context with operation list, which read the single context out of the kubeconfig on the test Mac. Every call that needs an actual cluster failed, as it had to. The sample call below is kubectl_get on nodes, and the excerpt is the error text it returned. What is pending here is not a password but a reachable cluster: this server treats your kubeconfig as the credential, and our Mac had exactly one context, a Docker Desktop endpoint with Kubernetes turned off. So nothing on this page claims a successful read from a live cluster. We also ran the server three more times on purpose to collect failures: with KUBECONFIG pointed at a file that does not exist, with an unknown context name, and in its non-destructive mode.
Startup banner
Starting Kubernetes MCP server v4.1.2, handling commands... Telemetry: Disabled
One real tool call
tools/call kubectl_get {"resourceType": "nodes"}MCP error -32603: Failed to execute kubectl get command: MCP error -32603: Failed to get resource: Command failed: kubectl get nodes -o json Unable to connect to the server: EOF
Real lines from the captured result: enough to prove the call answered.
Tools
Every tool, enumerated from the running server.
The server answered tools/list with 23 tools on 2026-08-03. The names, descriptions and parameters below are its own words, copied from that response and never edited.
| Tool | What it does |
|---|---|
| cleanup | Cleanup all managed resources |
| kubectl_getresourceType*namenamespaceoutputallNamespaceslabelSelectorfieldSelectorsortBycontext | Get or list Kubernetes resources by resource type, name, and optionally namespace |
| kubectl_describeresourceType*name*namespacecontextallNamespaces | Describe Kubernetes resources by resource type, name, and optionally namespace |
| kubectl_applymanifestfilenamenamespacedryRunforcecontext | Apply a Kubernetes YAML manifest from a string or file |
| kubectl_deleteresourceTypenamenamespacelabelSelectormanifestfilenameallNamespacesforcegracePeriodSecondscontext | Delete Kubernetes resources by resource type, name, labels, or from a manifest file |
| kubectl_createdryRunoutputvalidatemanifestfilenameresourceTypenamenamespacefromLiteralfromFilefromFileContentsecretTypeserviceTypetcpPortimagereplicasportschedulesuspendcommandlabelsannotationscontext | Create Kubernetes resources using various methods (from file or using subcommands) |
| kubectl_logsresourceType*name*namespace*containertailsincesinceTimetimestampspreviousfollowlabelSelectorcontext | Get logs from Kubernetes resources like pods, deployments, or jobs |
| kubectl_scalename*namespacereplicas*resourceTypecontext | Scale a Kubernetes deployment |
| kubectl_patchresourceType*name*namespacepatchTypepatchDatapatchFiledryRuncontext | Update field(s) of a resource using strategic merge patch, JSON merge patch, or JSON patch |
| kubectl_rolloutsubCommand*resourceType*name*namespace*revisiontoRevisiontimeoutwatchcontext | Manage the rollout of a resource (e.g., deployment, daemonset, statefulset) |
| kubectl_contextoperation*nameshowCurrentdetailedoutput | Manage Kubernetes contexts - list, get, or set the current context |
| kubectl_reconnect | Reconnect to the Kubernetes API server by recreating all API clients. Use this after cluster upgrades (e.g., EKS control plane upgrades that rotate ENIs/IPs) to force fresh DNS resolution and new TCP connections. |
| explain_resourceresource*apiVersionrecursivecontextoutput | Get documentation for a Kubernetes resource or field |
| install_helm_chartname*chart*namespace*contextrepovaluesvaluesFileuseTemplatecreateNamespace | Install a Helm chart with support for both standard and template-based installation |
| upgrade_helm_chartname*chart*namespace*contextrepovaluesvaluesFile | Upgrade an existing Helm chart release |
| uninstall_helm_chartname*namespace*context | Uninstall a Helm chart release |
| node_managementoperation*nodeNameforcegracePerioddeleteLocalDataignoreDaemonsetstimeoutdryRunconfirmDrain | Manage Kubernetes nodes with cordon, drain, and uncordon operations |
| port_forwardresourceType*resourceName*localPort*targetPort*namespace | Forward a local port to a port on a Kubernetes resource |
| stop_port_forwardid* | Stop a port-forward process |
| exec_in_podname*namespacecommand*containertimeoutcontext | Execute a command in a Kubernetes pod or container and return the output. Command must be an array of strings where the first element is the executable and remaining elements are arguments. This executes directly without shell interpretation for security. |
| list_api_resourcesapiGroupnamespacedcontextverbsoutput | List the API resources available in the cluster |
| kubectl_genericcommand*subCommandresourceTypenamenamespaceallNamespacesoutputFormatflagsargscontext | Execute any kubectl command with the provided arguments and flags |
| ping | Verify that the counterpart is still responsive and the connection is alive. |
Parameters marked with * are required.
Setup
Working configs, one per app.
Copy the block for the app you use. Each one is the configuration this server was verified with.
Claude Desktop
Open the file ~/Library/Application Support/Claude/claude_desktop_config.json (in Claude Desktop: Settings, then Developer, then Edit Config) and add:
{
"mcpServers": {
"kubernetes": {
"command": "npx",
"args": [
"-y",
"mcp-server-kubernetes"
]
}
}
}There is no key to paste, and that is deliberate: the server reads your kubeconfig, by default ~/.kube/config, and uses whichever context is current. Check that kubectl get pods works in a terminal first, then quit and reopen Claude Desktop. [10][5]
Claude Code
One command in your terminal:
claude mcp add kubernetes -- npx -y mcp-server-kubernetes
Everything after the double dash is the exact command Claude Code will run. It inherits the kubeconfig of the shell you run it from, so if your cluster needs KUBECONFIG or K8S_CONTEXT set, add them with --env KEY=value before the double dash. [11][6]
Cursor
Add to ~/.cursor/mcp.json for every project, or to .cursor/mcp.json inside one project:
{
"mcpServers": {
"kubernetes": {
"command": "npx",
"args": [
"-y",
"mcp-server-kubernetes"
]
}
}
}Cursor picks the file up on restart. To pin a context instead of following whatever kubectl is set to, add an "env" object next to "args" with K8S_CONTEXT in it. [12][6]
Routines
No JSON file and no terminal. In Routines: Settings, then Assistant, then Connections, then Add MCP Server. Switch the form to Command (stdio) and enter:
Name Kubernetes Command npx Arguments -y mcp-server-kubernetes
Leave Environment Variables empty unless you need a specific context or a kubeconfig outside ~/.kube/config, in which case add K8S_CONTEXT or KUBECONFIG there. Click Test Connection first: a working server answers with its tool count, twenty-three for this one. Note that the count comes back even when the cluster is unreachable, because the tool list is fixed and does not depend on the cluster. [13][6]
No terminal needed
Set the Kubernetes MCP server up without the terminal.
If you have never opened Terminal and never want to, this is your path, with one honest caveat: this particular server is a wrapper around kubectl, so kubectl and a working cluster have to exist first. Routines is a Mac app that runs MCP servers for you: fill in three fields once, and this server's tools are available to your AI in chat and in scheduled routines.
01
Install Routines
Download the app from getroutines.ai/download, drag it to Applications, and sign in.
02
Get kubectl talking to a cluster first
This is the credential step, and it is not a password. Install kubectl if you do not have it, then run kubectl get pods in Terminal once. If that prints pods or an empty list, you are ready. If it prints a connection error, fix that before going any further: the MCP server will hand you the same error, because it runs the same command.
03
Open the MCP settings
Click your account at the bottom of the sidebar and choose Settings. Open the Assistant section, then the Connections tab, scroll to MCP Servers, and click Add MCP Server.
04
Choose Command (stdio) and fill three fields
Switch the form to Command (stdio): this server is a command, not a web address. Name: Kubernetes. Command: npx. Arguments: -y mcp-server-kubernetes. Leave Environment Variables empty unless you need to pin a context, and then add K8S_CONTEXT with the context name.
05
Test, then add
Click Test Connection: Routines starts the server and reports how many tools it found, twenty-three for this one. That number arrives even if your cluster is down, so treat it as proof the server started, not proof the cluster answered. Then click Add Server.
06
Use it
The tools work in chat right away. Ask for something read-only first, like the pods in one namespace. To let a scheduled routine use them, open the routine, find the Tools & connections card, and tick the server under Apps.
Routine ideas
Routines worth scheduling.
Once the server is connected, a scheduled routine can use its tools while you are away. Copy a prompt, paste it into Routines, and pick a time.
A Friday capacity review
Prompt
Every Friday at 16:00, list the nodes in my cluster with their allocatable CPU and memory, list the deployments with their replica counts, and save the two tables to cluster-capacity.md with a one-line note on anything that changed since last week.
A daily failing-workload digest
Prompt
Every day at 18:00, find every deployment in my cluster with fewer ready replicas than desired, describe each one, and write a short digest of the likely cause to cluster-issues.md.
Troubleshooting
The errors we hit, and what fixed them.
Real errors captured during the verification run, printed exactly as the server returned them.
The tools are listed but every call fails to connect
What you see
MCP error -32603: Failed to execute kubectl get command: MCP error -32603: Failed to get resource: Command failed: kubectl get pods -n default -o json Unable to connect to the server: EOF
The fix
This is the state our test Mac was in, and it is the most common one: the server started, the tool list came back, and the cluster behind the current kubeconfig context is not answering. Run kubectl get pods in Terminal; you will get the same message, which tells you the problem is the cluster, not the MCP server. Start the cluster, or switch to a context that is up. The exact wording varies with how the endpoint fails: a dead port says connection refused, while a port that accepts the connection but has no Kubernetes behind it says EOF, which is what ours did.
The server exits immediately after starting
What you see
Error: ENOENT: no such file or directory, open '/private/tmp/does-not-exist-mcp-verify-2026.yaml'
at Object.openSync (node:fs:561:18)
at Object.readFileSync (node:fs:445:35)The fix
KUBECONFIG points at a file that is not there. We triggered this on purpose by setting it to a path we knew did not exist: the server throws while loading the kubeconfig, before it can speak MCP at all, so your client just reports that the server died. Fix the path, or remove KUBECONFIG entirely and let it fall back to ~/.kube/config.
A context name that does not exist returns a misleading answer
What you see
{
"error": "Resource nodes not found",
"status": "not_found"
}The fix
We asked for nodes with a context named does-not-exist. The tool answered as if the resource was missing, while the real cause appeared only on the server's own output: Error in configuration: context was not found for specified context: does-not-exist. If a query comes back not_found and you are passing a context, check the spelling first with the kubectl_context tool, which lists the contexts your kubeconfig actually has.
A tool you expected is missing or refuses to run
What you see
MCP error -32600: Tool 'kubectl_delete' is not allowed under the current server configuration
The fix
The server was started in non-destructive mode, with ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS set to true. We ran it that way on purpose: the tool list drops from 23 to 18, kubectl_delete, kubectl_generic, node_management, uninstall_helm_chart and cleanup disappear, and calling one anyway returns this. That is a feature worth using on a real cluster. Remove the environment variable to get the full set back.
Your MCP client cannot start the server at all
The fix
The npx command belongs to Node.js. If Node is not installed on your Mac, every client on this page fails at the spawn step before the server can say anything. Install Node from nodejs.org, restart your MCP client, and try again. The same class of failure happens without kubectl: the server starts, but every tool call fails at the point where it tries to run the binary.
FAQ
Questions people ask.
What is the Kubernetes MCP server?
It is a local server that gives an AI assistant the kubectl surface of your cluster over the Model Context Protocol. The package with the most downloads, mcp-server-kubernetes, runs on your Mac over stdio and drives the kubectl binary already installed there, so anything you can do with kubectl in a terminal, the assistant can ask for in plain English: list pods, describe a deployment, read logs, scale, apply a manifest, install a Helm chart. [5][1]
What tools does the Kubernetes MCP server include?
The running server exposes 23 tools: reading (kubectl_get, kubectl_describe, kubectl_logs, explain_resource, list_api_resources), writing (kubectl_apply, kubectl_create, kubectl_patch, kubectl_scale, kubectl_rollout, kubectl_delete), nodes and access (node_management, port_forward, stop_port_forward, exec_in_pod), Helm (install_helm_chart, upgrade_helm_chart, uninstall_helm_chart), context and plumbing (kubectl_context, kubectl_reconnect, kubectl_generic, cleanup, ping). The table above is the live tools/list output, word for word.
Does it need an API key or an account?
No. There is nothing to sign up for and no credential to paste. What it needs instead is infrastructure: kubectl installed and on your PATH, and a kubeconfig with a context pointing at a cluster you can already reach. If kubectl get pods works in your terminal, the server will work; if it does not, the server returns the same error kubectl does. [5]
What did you verify, and what did you not?
We verified that the server starts, speaks the protocol, and exposes exactly 23 tools, and we kept the raw output. We did not verify a single read from a live cluster, because the test Mac had no cluster running: its one kubeconfig context points at a Docker Desktop endpoint with Kubernetes switched off, so calls came back with a connection error, which you can read verbatim above. Two calls did answer, ping and kubectl_context, and neither of them touches a cluster. Treat the tool table as measured and the cluster behaviour as unverified here.
mcp-server-kubernetes or kubernetes-mcp-server, which one is this?
Two different projects with almost the same name, and this page is about the first one, mcp-server-kubernetes by flux159: 23,344 npm downloads in the week ending 2026-08-01, MIT licensed, written in TypeScript, and a wrapper around kubectl and helm. The other one, kubernetes-mcp-server from the containers organisation, pulled 13,437 downloads in the same week, is Apache-2.0, is written in Go and talks to the Kubernetes API directly with no kubectl needed, supports OpenShift, and is the one listed in the official MCP registry. Fewer downloads, more stars, different trade-off. [2][7][8][9][4]
Is it safe to give an assistant this much cluster access?
By default it is full read and write: kubectl_delete, node drains and helm uninstalls are all in the list. The server ships two narrower modes, and we tested one of them: starting it with ALLOW_ONLY_NON_DESTRUCTIVE_TOOLS set to true dropped the tool list from 23 to 18 and made a delete call come back refused, which is printed in the troubleshooting section. There is also a read-only mode. Use one of them, and point the server at a context with limited rights rather than a cluster-admin one. [6]
Which apps can use the Kubernetes MCP server?
Any MCP client that can launch a local stdio server: Claude Desktop, Claude Code, Cursor, and Routines all can, and the exact config for each is above. The server itself is the same in every client; only the place you paste the config differs, and each one inherits whichever kubeconfig the process it starts can see. [10][11][12][13]
Sources
Every external claim, receipted.
Anything on this page we did not observe in the run is linked here, with the date we read it. The run itself is the receipt for the rest.
[1]
npm registry: mcp-server-kubernetesaccessed 2026-08-03Latest version 4.1.2, published 2026-07-29, license MIT, maintainer flux159.
[2]
[3]
GitHub: Flux159/mcp-server-kubernetesaccessed 2026-08-031,516 stars and a push dated 2026-07-29 at access time, per the GitHub API.
[4]
mcp-server-kubernetes LICENSE fileaccessed 2026-08-03MIT License, Copyright (c) 2024 Suyog Sonwalkar.
[5]
mcp-server-kubernetes READMEaccessed 2026-08-03Prerequisites: kubectl on your PATH, a valid kubeconfig, cluster access, Helm v3 optional. Also the per-client config blocks.
[6]
mcp-server-kubernetes ADVANCED_READMEaccessed 2026-08-03KUBECONFIG, KUBECONFIG_PATH, K8S_CONTEXT and K8S_NAMESPACE, plus the read-only and non-destructive modes.
[7]
npm downloads API: kubernetes-mcp-server, last weekaccessed 2026-08-0313,437 downloads for the week ending 2026-08-01.
[8]
GitHub: containers/kubernetes-mcp-serveraccessed 2026-08-03The other Kubernetes MCP server: 1,874 stars, Apache-2.0, written in Go, per the GitHub API.
[9]
Official MCP registry searchaccessed 2026-08-03Lists io.github.containers/kubernetes-mcp-server up to 0.0.66; a search for mcp-server-kubernetes returns zero results.
[10]
modelcontextprotocol.io: Connect to local MCP serversaccessed 2026-08-03The official Claude Desktop quickstart and the config file location.
[11]
Claude Code docs: MCPaccessed 2026-08-03The claude mcp add syntax for local stdio servers, including --env KEY=value for environment variables.
[12]
[13]
Routines: Connectorsaccessed 2026-08-03How Routines runs one-click OAuth connectors and any MCP server.
This page describes Kubernetes as it behaved in one dated run on one Mac. Versions move: if something here no longer matches what you see, the capture date at the top says how old the reading is.
Behind this directory
Routines, the app behind this directory, runs MCP servers like this one without a terminal: see how connectors work. Your notes stay markdown files on your Mac, there is no cloud bill, and it works offline. Download Routines