MCP server — connect Claude, ChatGPT & any AI agent¶

HomeLab Monitor ships a built-in Model Context Protocol (MCP) server so an AI agent — Claude, ChatGPT, or any MCP-capable client — can connect to the monitor and explore the whole homelab ecosystem through it: hosts, containers, systemd services, GPU, AI model servers, alerts and host posture.

It's a thin, well-described wrapper over the monitor's existing read-only HTTP endpoints. No collectors are touched, and nothing is mutated.

Read-only by design

There are no write tools. Any future write capability (run a probe, restart a container, apply an OS update) must be opt-in, clearly labelled destructive, and gated behind explicit config — same philosophy as the rest of the project.

Tools¶

Everything the dashboard shows is reachable through these tools. The usual path is list_hosts → get_host → get_snapshot, then a detail tool.

Tool	What it answers	Wraps
`list_hosts()`	What's in the fleet, and is it healthy?	`/api/fleet`
`get_host(name)`	One host's System / Network / Security inventory (`"local"` = the hub)	`/api/host_data/<name>`
`get_snapshot()`	Live GPU / host / Docker / systemd overview + diagnostics	`/api/health`
`get_containers()`	Full Docker list — state, health, ports, RAM/VRAM, image disk, uptime	`/api/health`
`get_services()`	Full systemd list — active/sub state, ports, RAM, admin/watched flags	`/api/health`
`get_memory(range)`	Per-service & per-process RAM breakdown (the memory treemap)	`/api/data`
`get_gpu(range)`	GPU util / VRAM / power / temp, per-model VRAM, caller attribution	`/api/data`
`get_ai_models(range)`	Which models are loaded, their VRAM, and who is driving them	`/api/data`
`get_history(range)`	Charted time-series (GPU + host) for trends	`/api/data`
`get_events(range)` / `get_alerts(range)`	Recent OOM kills / threshold crossings + insights	`/api/data`
`scan_disk(path, rescan)`	WizTree-style nested folder-size treemap	`/api/disk_scan`

range accepts the same windows as the dashboard, e.g. 6h, 24h, 7d. scan_disk takes an absolute host path (e.g. /, /var) and polls the background scan until it's done.

Resources¶

Resource	Content
`homelab://metrics`	Prometheus exposition text (`/metrics`)
`homelab://health`	Liveness + running version (`/healthz`)
`homelab://changelog`	The bundled CHANGELOG, for version context

Configuration¶

Env	Default	Meaning
`HOMELAB_MONITOR_URL`	`http://localhost:9800`	Base URL of the monitor to read
`HOMELAB_HTTP_TIMEOUT`	`10`	Per-request timeout (seconds)
`MCP_TRANSPORT`	`stdio`	`stdio`, or `http` (streamable-http) for the sidecar
`MCP_HOST` / `MCP_PORT`	`0.0.0.0` / `9810`	Bind address for the `http` transport

Run it¶

The MCP server is built into the monitor image and served on MCP_PORT (default 9810) alongside the dashboard — there's nothing extra to deploy. Set ENABLE_MCP=0 to turn it off.

Connect (built-in, HTTP)Local Python (dev, stdio)Docker stdio (advanced)

# the dashboard is already running on :9800; the MCP server is on :9810
claude mcp add --transport http homelab http://YOUR-HUB:9810/mcp

Run the server straight from a checkout against any monitor:

pip install -r mcp/requirements.txt   # Python 3.10+
HOMELAB_MONITOR_URL=http://YOUR-HUB:9800 python mcp/server.py

The same image can also be driven over stdio against a remote monitor:

claude mcp add homelab -- docker run -i --rm \
  -e HOMELAB_MONITOR_URL=http://YOUR-HUB:9800 -e MCP_TRANSPORT=stdio \
  sikamikaniko123/homelab-monitor python /app/mcp_server.py

Try it¶

Once connected, ask your agent natural questions and let it pick the tools:

"Which host has a reboot pending and an OS upgrade available — what's the safe order to apply it?"
"Why is the GPU pinned right now, and which service is calling the model server?"
"Any OOM kills in the last 24h? What got blamed?"

Keep it on your LAN/VPN

Like the dashboard, the MCP server gives broad visibility into your hosts. Don't expose either to the public internet.