cluster_summaryLABSCO SUMMARY
An agent with cluster access, and a brake it cannot reach around.
The allowlist is enforced before the API call rather than by asking the model to behave, which is what makes this attachable to a cluster you care about. The cluster summary is the sensible opening call: it returns the unhealthy pods rather than everything.
What it is
A Python MCP server that talks to the Kubernetes API through your existing kubeconfig, or an in-cluster service account. Reads are always on; restart, scale and delete are gated by a read-only switch and a namespace allowlist before the API call is made.
What you get
- A one-call cluster summary: node and pod totals, plus the unhealthy pods
- Pods, deployments and events listed
- Pod logs and node health read back
- A deployment rollout-restarted or scaled
- A pod deleted
- Mutations blocked unless the namespace is on your allowlist, and HOMELAB_MCP_READONLY=1 to make the whole server read-only
Requirements
A reachable cluster and a working kubeconfig — the same one kubectl uses — or an in-cluster service account. Python 3.11+, or run it with uvx. The PyPI package is whitecapdata-dev.
Setup effort
One command — uvx whitecapdata-dev
USE CASES
01
Finding out what is broken right now
Take the cluster summary — node and pod totals with the unhealthy pods already picked out — then list pods where it points.
02
Tracing why a pod is unhealthy
Read the events around it and then its logs, in the same thread.
03
Restarting something that has wedged
Find the deployment and roll it, inside a namespace you put on the allowlist.
04
Handling a change in load
Read the current replica count and scale the deployment to what the traffic needs.
05
Clearing a pod that will not recover
Delete it and let the controller replace it — blocked outright unless its namespace is allowlisted.
06
Checking the nodes rather than the workloads
Read node health alongside the cluster summary, when the pods look fine but the box does not.
10 tools
Listed in project docs. Your client may show a different list.
list_podslist_deploymentslist_eventspod_logsnode_healthrestart_deploymentscale_deploymentdelete_podserver_infoBEFORE YOU INSTALL
What to know first
Tools you get
10 tools named in the project's documentation.
Requires
- uvx on PATH
- Python 3.11+
INSTALLATION
Connect your client
Server setup
TERMINAL
uvx whitecapdata-devMCP Clients
Claude Code
CLAUDE CODE · TERMINAL
claude mcp add homelab -- uvx whitecapdata-devClaude Desktop, Cursor
JSON
{
"mcpServers": {
"homelab": {
"command": "uvx",
"args": [
"whitecapdata-dev"
],
"env": {
"HOMELAB_MCP_MUTABLE_NAMESPACES": "default,apps,monitoring",
"HOMELAB_MCP_READONLY": "0"
}
}
}
}
