Tool reference

Sixteen tools and two prompts. You never call these by hand — Claude picks them based on what you ask. Knowing what exists helps you ask better questions, and helps you judge what you are actually granting.

Read tools work as soon as the server is registered. Write tools refuse unless the server was started with MICROK8S_MCP_MODE=read-write, and several need a further switch on top of that.

Read tools always available

cluster_overview()

A snapshot of cluster health: nodes, MicroK8s addons, namespaces, workloads that are not Running or Completed, and recent warning events. This is the orientation tool — Claude is told to start here for open-ended questions.

No arguments. Sections that fail degrade individually, so a missing node backend still leaves you the kubectl half.

list_resources(kind, …)

Lists resources of a kind: pods, deployments, services, ingresses, PVCs, nodes, CRDs — anything the cluster knows about.

Arguments: kind, namespace, all_namespaces, selector (label selector, e.g. app=web), field_selector, output (wide, name, json, yaml).

get_resource(kind, name, …)

Fetches the full manifest of a single object.

Arguments: kind, name, namespace, output (yaml or json).

describe_resource(kind, name, …)

kubectl describe: status, conditions and the object's recent events. Usually the best first step when something is failing, because it bundles the events that explain why.

Arguments: kind, name, namespace.

get_logs(pod, namespace, …)

Container logs for a pod, including the logs of a crashed previous container — which is where the actual cause of a crash loop usually lives.

Arguments: pod, namespace, container, tail_lines (default 200, capped at 5000), since (durations like 15m or 2h), previous.

get_events(…)

Cluster events, newest last, warnings only by default.

Arguments: namespace, all_namespaces, only_warnings (default true).

top(scope, …)

CPU and memory usage for nodes or pods. Requires the metrics-server addon — enable it with microk8s enable metrics-server.

Arguments: scope (nodes or pods), namespace.

api_resources()

Every resource kind the cluster knows about, including CRDs. Useful when it is not obvious what kind to pass to the other tools.

No arguments.

rollout_status(kind, name, namespace)

Current rollout state of a deployment, statefulset or daemonset. Times out after 20 seconds rather than blocking on a rollout that is stuck.

Arguments: kind, name, namespace.

microk8s_status()

MicroK8s snap status: whether the cluster is running, its HA state, and which addons are enabled. Needs the node backend — either the server runs on the node, or MICROK8S_MCP_SSH_HOST is set.

No arguments.

Write tools read-write mode

All six refuse with a clear message unless MICROK8S_MCP_MODE=read-write. Each also honours the namespace allowlist and the protected-namespace rule.

apply_manifest(manifest_yaml, …)

Applies a YAML manifest, including multi-document YAML. Defaults to a server-side dry run and returns a diff, so the intended workflow is: call once with dry_run=True, look at the diff, then call again with dry_run=False to commit.

Arguments: manifest_yaml, namespace, dry_run (default true).

scale_workload(kind, name, namespace, replicas)

Scales a deployment, statefulset or replicaset. Replica counts are clamped to 0–100.

Arguments: kind, name, namespace, replicas.

rollout_restart(kind, name, namespace)

Triggers a rolling restart of a deployment, statefulset or daemonset.

Arguments: kind, name, namespace.

delete_resource(kind, name, namespace, confirm) destructive

Deletes one named resource, and requires confirm=True. Bulk and selector deletes are deliberately not supported — there is no --all path, so the blast radius of any single call is one object.

Arguments: kind, name, namespace, confirm (default false).

manage_addon(action, addon, …)

Enables or disables a MicroK8s addon: dns, ingress, storage, metrics-server, cert-manager, registry and the rest. Needs MICROK8S_MCP_ALLOW_ADDON_CHANGES=true on top of read-write mode.

Arguments: action (enable/disable), addon, arguments (passed after a colon, e.g. size=40Gi).

This runs microk8s enable/disable on the node, which is snap-level root. RBAC does not constrain it in any way.

node_maintenance(action, node, confirm) destructive

Cordons, uncordons or drains a node. Needs MICROK8S_MCP_ALLOW_NODE_OPS=true; cordon and drain also require confirm=True.

Arguments: action (cordon/uncordon/drain), node, confirm.

On a single-node MicroK8s install, a drain evicts everything with nowhere to reschedule it. That is your whole cluster down.

Prompts

Two ready-made workflows, available from the prompt picker in Claude Code.

triage_namespace(namespace)

Walks through diagnosing a broken namespace: list what is there, describe anything not Ready, pull logs (including previous-container logs for crash loops), check warning events, then report a likely root cause and propose a fix — explicitly without changing anything first.

health_report()

A short cluster health report: node conditions and capacity, enabled addons, unhealthy workloads, PVCs that are not Bound, and anything in the warning events worth acting on.

How arguments are validated

Every tool argument that reaches a command line is checked first. This is the part that keeps model output from turning into an unintended kubectl flag.

Kinds, names, containers and nodes must match ^[a-zA-Z0-9][a-zA-Z0-9._/-]*$ — so a "name" of --all is rejected outright, because it does not start with an alphanumeric.
Namespaces must match ^[a-z0-9][a-z0-9-]{0,62}$, then pass the allowlist, then — for writes — the protected-namespace check.
Commands are argument lists, never strings. Nothing is passed through a shell, so shell metacharacters have no meaning. Remote SSH commands are quoted per argument with shlex.quote.
Output is clipped at MICROK8S_MCP_MAX_OUTPUT characters, keeping both ends and noting what was dropped.

The test suite covers exactly these paths — argument injection, read-only refusal, the confirm=True requirement, and backend selection.