WhiteCapData MCP Server

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

Local serverstdioPython

What is the WhiteCapData MCP Server?

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

What you get

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).

  • 🩺 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

Configuration and credentials

  • 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).

More MCP options

Compare MCP servers by category, or browse hosted MCP servers if you prefer an endpoint over a local process.

Maintainer setup documentation.

Recorded tools

Check the linked publisher documentation and your connected client's tool list. Names and availability can vary with the server version and account permissions.

ToolWhat it does
cluster_summaryread
list_podsread
list_deploymentsread
list_eventsread
pod_logsread
node_healthread
restart_deploymentwrite
scale_deploymentwrite
delete_podwrite
server_inforead

How to install the WhiteCapData MCP Server

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

From the project documentation. Replace placeholders and example paths before connecting.

Configuration

  • 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).
VariableDescriptionRequired
HOMELAB_MCP_MUTABLE_NAMESPACESDeclared in the maintainer’s client configuration.Check documentation
HOMELAB_MCP_READONLYDeclared in the maintainer’s client configuration.Check documentation

Example prompts to try

  • “Use WhiteCapData to cluster summary.”
  • “Use WhiteCapData to list pods.”
  • “Use WhiteCapData to list deployments.”

Frequently asked questions

Operate a k3s / Kubernetes cluster from your AI agent — safe-by-default MCP server. Confirm the tools offered by your installed version in the connected client. Tool availability and permissions depend on the server and account configuration.