WhiteCapData Dev

Official

by Michael-WhiteCapData · Python

Operate a k3s / Kubernetes cluster from your AI agent — safe-by-default MCP server.

Manage a k3s/Kubernetes cluster from an AI agent with safe defaults.

Topics

claudedevopshomelabk3skubernetesmcpmodel-context-protocolpython

README.md5 KBView on GitHub

WhiteCapData-Dev

Operate a k3s / Kubernetes cluster straight from your AI agent — safe by default.

An MCP server that lets an agent (Claude Code, Claude Desktop, Cursor, …) inspect and operate a Kubernetes / k3s cluster — your homelab box, a dev cluster, whatever your kubeconfig points at — without shelling out to kubectl. It talks to the Kubernetes API directly using your existing kubeconfig (or an in-cluster service account).

The design goal is safe by default: reads are always on; every mutating action (restart / scale / delete) is gated before the API call by a read-only switch and a namespace allowlist, so an over-eager agent can't touch kube-system or nuke a deployment you didn't sandbox.

Name note: the PyPI package is whitecapdata-dev (the homelab-k8s-style name was taken); the import package and tools are k8s/homelab-focused as described here.

Why you'd want this

🩺 One-call health. cluster_summary gives node + pod totals and the unhealthy pods, so the agent starts triage with real data.
🔒 Safe by default. Mutations are blocked unless the namespace is on your allowlist; flip HOMELAB_MCP_READONLY=1 to make the whole server read-only.
🧰 The operations you actually do. Pods, deployments, events, logs, node health, rollout-restart, scale, delete-pod.
🪶 No bespoke backend. Uses the standard Kubernetes API + your kubeconfig — nothing to deploy server-side.
✅ Tested. Pure logic is unit-tested with fakes; guard logic is tested against a mocked API. No cluster needed to run the suite.

Requirements

A reachable cluster and a working kubeconfig (the same one kubectl uses), or run it in-cluster with a service account.
Python 3.11+ (or just uvx).

Install

bash

uvx whitecapdata-dev          # run directly
# or
pip install whitecapdata-dev  # then run: whitecapdata-dev

Claude Code

bash

claude mcp add homelab -- uvx whitecapdata-dev

Claude Desktop / Cursor

jsonc

{
  "mcpServers": {
    "homelab": {
      "command": "uvx",
      "args": ["whitecapdata-dev"],
      "env": {
        "HOMELAB_MCP_MUTABLE_NAMESPACES": "default,apps,monitoring",
        "HOMELAB_MCP_READONLY": "0"
      }
    }
  }
}

Run with Docker

A Dockerfile is included. The server speaks MCP over stdio and reaches your cluster through a mounted kubeconfig. Run interactively (-i), starting read-only:

bash

docker build -t whitecapdata-dev .
docker run --rm -i \
  -v "$HOME/.kube/config:/home/app/.kube/config:ro" \
  -e HOMELAB_MCP_READONLY=1 \
  whitecapdata-dev

Tools

Tool	Kind	Description
`cluster_summary`	read	Node/pod health totals + unhealthy pods
`list_pods`	read	Pods (optionally one namespace), unhealthy first
`list_deployments`	read	Deployments with ready/desired replicas
`list_events`	read	Recent events, Warnings first
`pod_logs`	read	Tail a pod's logs
`node_health`	read	Per-node readiness, kubelet, capacity, pressure
`restart_deployment`	write	Rollout-restart (allowlisted namespaces)
`scale_deployment`	write	Scale to N replicas (0..max, allowlisted)
`delete_pod`	write	Delete a pod; its controller recreates it (allowlisted)
`server_info`	read	Effective config (context, read-only, allowlist)

Configuration

Variable	Default	Description
`HOMELAB_MCP_CONTEXT`	current-context	kubeconfig context to use
`HOMELAB_MCP_READONLY`	`0`	`1`/`true` disables all mutating tools
`HOMELAB_MCP_MUTABLE_NAMESPACES`	`default,apps,monitoring,ci`	Namespaces mutations may touch; `*` = all
`HOMELAB_MCP_MAX_REPLICAS`	`10`	Upper bound for `scale_deployment`

Safety model

Read-only switch — HOMELAB_MCP_READONLY=1 rejects every mutating tool up front.
Namespace allowlist — mutating tools refuse any namespace not in HOMELAB_MCP_MUTABLE_NAMESPACES (default a homelab-friendly set; * opts into all).
Bounded scale — scale_deployment clamps to 0..HOMELAB_MCP_MAX_REPLICAS.

The cluster's own RBAC still applies on top — this server can only do what the kubeconfig identity is permitted to do.

Development

bash

git clone https://github.com/Michael-WhiteCapData/WhiteCapData-Dev
cd WhiteCapData-Dev
uv pip install -e ".[dev]"
ruff check .
pytest          # no cluster required — APIs are faked/mocked

See CONTRIBUTING.md.

License

Install

Configuration

Environment variables

HOMELAB_MCP_CONTEXT

kubeconfig context to use (defaults to current-context).

HOMELAB_MCP_READONLYdefault 0

Set to 1/true to disable all mutating tools.

HOMELAB_MCP_MUTABLE_NAMESPACESdefault default,apps,monitoring,ci

Comma-separated namespaces mutations may touch; '*' allows all.

HOMELAB_MCP_MAX_REPLICASdefault 10

Upper bound accepted by scale_deployment.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "WhiteCapData-Dev": {
      "command": "uvx",
      "args": [
        "whitecapdata-dev"
      ],
      "env": {
        "HOMELAB_MCP_CONTEXT": "<YOUR_HOMELAB_MCP_CONTEXT>",
        "HOMELAB_MCP_READONLY": "0",
        "HOMELAB_MCP_MUTABLE_NAMESPACES": "default,apps,monitoring,ci",
        "HOMELAB_MCP_MAX_REPLICAS": "10"
      }
    }
  }
}