{
  "markdown": "<!-- mcp-name: io.github.Michael-WhiteCapData/WhiteCapData-Dev -->\n\n# WhiteCapData-Dev\n\n**Operate a k3s / Kubernetes cluster straight from your AI agent — safe by default.**\n\n[![CI](https://github.com/Michael-WhiteCapData/WhiteCapData-Dev/actions/workflows/ci.yml/badge.svg)](https://github.com/Michael-WhiteCapData/WhiteCapData-Dev/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/whitecapdata-dev?color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/whitecapdata-dev/)\n[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-server-D97757)](https://modelcontextprotocol.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\nAn [MCP](https://modelcontextprotocol.io/) 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).\n\nThe 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.\n\n> **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.\n\n---\n\n## Why you'd want this\n\n- 🩺 **One-call health.** `cluster_summary` gives node + pod totals and the unhealthy pods, so the agent starts triage with real data.\n- 🔒 **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.\n- 🧰 **The operations you actually do.** Pods, deployments, events, logs, node health, rollout-restart, scale, delete-pod.\n- 🪶 **No bespoke backend.** Uses the standard Kubernetes API + your kubeconfig — nothing to deploy server-side.\n- ✅ **Tested.** Pure logic is unit-tested with fakes; guard logic is tested against a mocked API. No cluster needed to run the suite.\n\n## Requirements\n\n- A reachable cluster and a working **kubeconfig** (the same one `kubectl` uses), or run it in-cluster with a service account.\n- Python 3.11+ (or just `uvx`).\n\n## Install\n\n```bash\nuvx whitecapdata-dev          # run directly\n# or\npip install whitecapdata-dev  # then run: whitecapdata-dev\n```\n\n### Claude Code\n\n```bash\nclaude mcp add homelab -- uvx whitecapdata-dev\n```\n\n### Claude Desktop / Cursor\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"homelab\": {\n      \"command\": \"uvx\",\n      \"args\": [\"whitecapdata-dev\"],\n      \"env\": {\n        \"HOMELAB_MCP_MUTABLE_NAMESPACES\": \"default,apps,monitoring\",\n        \"HOMELAB_MCP_READONLY\": \"0\"\n      }\n    }\n  }\n}\n```\n\n## Run with Docker\n\nA [`Dockerfile`](Dockerfile) is included. The server speaks MCP over stdio and reaches\nyour cluster through a mounted kubeconfig. Run interactively (`-i`), starting read-only:\n\n```bash\ndocker build -t whitecapdata-dev .\ndocker run --rm -i \\\n  -v \"$HOME/.kube/config:/home/app/.kube/config:ro\" \\\n  -e HOMELAB_MCP_READONLY=1 \\\n  whitecapdata-dev\n```\n\n## Tools\n\n| Tool | Kind | Description |\n| --- | --- | --- |\n| `cluster_summary` | read | Node/pod health totals + unhealthy pods |\n| `list_pods` | read | Pods (optionally one namespace), unhealthy first |\n| `list_deployments` | read | Deployments with ready/desired replicas |\n| `list_events` | read | Recent events, Warnings first |\n| `pod_logs` | read | Tail a pod's logs |\n| `node_health` | read | Per-node readiness, kubelet, capacity, pressure |\n| `restart_deployment` | **write** | Rollout-restart (allowlisted namespaces) |\n| `scale_deployment` | **write** | Scale to N replicas (0..max, allowlisted) |\n| `delete_pod` | **write** | Delete a pod; its controller recreates it (allowlisted) |\n| `server_info` | read | Effective config (context, read-only, allowlist) |\n\n## Configuration\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `HOMELAB_MCP_CONTEXT` | current-context | kubeconfig context to use |\n| `HOMELAB_MCP_READONLY` | `0` | `1`/`true` disables all mutating tools |\n| `HOMELAB_MCP_MUTABLE_NAMESPACES` | `default,apps,monitoring,ci` | Namespaces mutations may touch; `*` = all |\n| `HOMELAB_MCP_MAX_REPLICAS` | `10` | Upper bound for `scale_deployment` |\n\n## Safety model\n\n1. **Read-only switch** — `HOMELAB_MCP_READONLY=1` rejects every mutating tool up front.\n2. **Namespace allowlist** — mutating tools refuse any namespace not in `HOMELAB_MCP_MUTABLE_NAMESPACES` (default a homelab-friendly set; `*` opts into all).\n3. **Bounded scale** — `scale_deployment` clamps to `0..HOMELAB_MCP_MAX_REPLICAS`.\n\nThe cluster's own RBAC still applies on top — this server can only do what the kubeconfig identity is permitted to do.\n\n## Development\n\n```bash\ngit clone https://github.com/Michael-WhiteCapData/WhiteCapData-Dev\ncd WhiteCapData-Dev\nuv pip install -e \".[dev]\"\nruff check .\npytest          # no cluster required — APIs are faked/mocked\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## License\n\n[MIT](LICENSE) © Michael Tierney\n",
  "bytes": 5304,
  "sha": "65e2a843c63e298dba93689389435df30c44bbb5fc8ffcacf95cf00ef35dbe8c",
  "repo_slug": "michael-whitecapdata/whitecapdata-dev",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_michael_whitecapdata_whitecapd_cbfa123f/readme"
}