Connect Kubernetes to Claude Code
Inspect pods, deployments, nodes and events on a cluster, and read pod logs. Add Toolspoke to Claude Code once and it can use 12 Kubernetes actions. Your Kubernetes credential stays in Toolspoke, and you choose which actions Claude Code may call.
Set it up in Claude Code
Three steps, the first one once for every toolkit you will ever add.
Add Toolspoke to Claude Code
Run it in your project, then /mcp to sign in
claude mcp add --transport http toolspoke https://toolspoke.com/mcpThe sign-in opens in your browser, and Toolspoke asks you to approve it.
Install Kubernetes and connect it
Add Kubernetes to a project in your Toolspoke workspace.
Service account token. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.
- Service account token
- A ServiceAccount bearer token: create the account, bind it to a role, then mint a token with `kubectl create token <name> --duration=…`. Bind it to view for read-only, and grant delete on pods and update on deployments/scale only if you want the write actions to work.
- API server URL
- The cluster's publicly reachable API server endpoint, e.g. the control plane URL from your kubeconfig. Private-network and cluster-internal addresses are refused, this never reaches a socket or a local kubectl proxy.
Choose what Claude Code may do
All 12 actions start on. Switch off any of the 2 actions that change something in Kubernetes, and Claude Code gets a refusal if it tries.
What you can ask Claude Code for
A few of the Kubernetes actions that only read, so they are safe to try first.
- List the namespaces on the cluster with their phase
- List the pods in a namespace with their phase, restart counts and node
- Read the tail of one container's log
- List the deployments in a namespace with their desired, updated, ready and available replica counts
What Claude Code can do in Kubernetes
10 actions read, one writes and one deletes or permanently changes something.
Reads
List namespaces
List the namespaces on the cluster with their phase. Call this first when you do not know which namespace an application runs in, every other action here except list_nodes is namespace-scoped.
List pods
List the pods in a namespace with their phase, restart counts and node. Start here when something is unhealthy: the restart count and the container statuses usually say which pod to look at, and the pod name is what get_pod, get_pod_logs and delete_pod need. Narrow with label_selector (e.g. app=checkout) or field_selector (e.g. status.phase=Running).
Get pod
Fetch one pod's full object: containers and images, resource requests and limits, volumes, conditions, and per-container state including the reason a container last terminated. This is where CrashLoopBackOff, OOMKilled and ImagePullBackOff are actually explained. Read the logs with get_pod_logs afterwards.
Get pod logs
Read the tail of one container's log. Pass container when the pod runs more than one, or the API server refuses the request and names the choices. Set previous to true to read the log of the container that crashed rather than the one that replaced it, that is usually the log you actually want. Output is capped at roughly 20000 characters, keeping the most recent lines.
List deployments
List the deployments in a namespace with their desired, updated, ready and available replica counts. A deployment whose ready count is below its desired count is the usual first sign of a rollout that stalled. The deployment name is what get_deployment and scale_deployment need.
Get deployment
Fetch one deployment in full: its pod template, images, replica strategy, and the conditions explaining a rollout that is not progressing. Call this before scale_deployment so you know the current replica count you are changing.
List services
List the services in a namespace with their type, cluster IP, ports and selector. Use it to check that a service's selector actually matches the labels on the pods list_pods returned, a service selecting nothing is a common cause of "the app is up but nothing reaches it".
List nodes
List the cluster's nodes with their conditions, capacity and allocatable resources. Use it when pods are stuck Pending, a node under MemoryPressure or DiskPressure, or one that is NotReady, explains that where the pod object does not. This is the one action here that is not namespace-scoped.
List events
List the recent events in a namespace, scheduling failures, image pull errors, probe failures, evictions and scaling decisions, in the cluster's own words. This is the fastest explanation of why a pod will not start, and it says things no object status does. Narrow to one object with field_selector, e.g. "involvedObject.name=checkout-7c9".
Describe resource
Fetch any core-v1 namespaced object by kind and name, for the things that have no dedicated action here: configmaps, endpoints, persistentvolumeclaims, serviceaccounts, replicationcontrollers. Use it to check what a pod is actually mounting, or whether a service has any endpoints behind it. Only core-v1 kinds are reachable, deployments and pods have their own actions above.
Writes
Scale deployment
Set a deployment's replica count by patching its scale subresource. Scaling to 0 takes the workload down and scaling up costs capacity, so read get_deployment first and put the count back when you are done. A HorizontalPodAutoscaler will overwrite this within its next sync interval.
Deletes or permanently changes
Delete pod
Delete a pod. In practice this restarts it: anything owned by a Deployment, StatefulSet or DaemonSet is recreated immediately, which is the usual remediation for a wedged or leaking process. A pod with no controller is simply gone, and its logs go with it, read get_pod_logs first. This changes what the on-call rota sees, because the restart shows up as an event and may re-trigger a probe alert.
Kubernetes in Claude Code: questions
Does Claude Code see my Kubernetes credential?
No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Claude Code only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.
Can I stop Claude Code from changing things in Kubernetes?
Yes. Each of the 12 actions can be switched off for a project. Turn off the 2 that change something and Claude Code can only read.
Will 12 actions crowd Claude Code's context?
No. Toolspoke shows Claude Code five bridge tools, plus a guide where a toolkit has one, and Claude Code searches for the Kubernetes action it needs when it needs it. Adding more toolkits does not add more tools to its list.
Can I add it once for every project?
Yes. Add --scope user to the command and Claude Code keeps Toolspoke in every project on this machine. Without it, the server is added to the project you ran the command in.
What does it cost?
Tool calls are free on every plan, and a Kubernetes call does not run in a sandbox, so it bills nothing.
Kubernetes in your other apps
More infrastructure toolkits for Claude Code
Try Kubernetes in Claude Code
Free to start, and tool calls cost nothing on any plan.