Skip to main content
Glama
homelab-mcp

homelab-mcp

by Chain-P

homelab-mcp

Raspberry Pi homelab status, exposed as an MCP server — so an MCP client (Claude Code, Claude Desktop) can be asked "how's the homelab doing?" and get real systemd service health, disk usage, CPU temp, and the LAN game-server feed back directly, instead of SSHing in and checking by hand.

Read-only by design: every tool queries state, nothing restarts, stops, or reboots anything.

Claude Code asking whether zero-bot is running and getting real systemd status back

Architecture

The server runs on the Pi itself — not on the machine running the MCP client — since that's where the systemd units, disk, and thermal sensor actually are. The MCP client reaches it over SSH-tunneled stdio: SSH just exposes a local stdio process to a remote client, no special MCP-side support needed.

MCP client (laptop) --ssh--> homelab-mcp server (on the Pi) --> systemctl / /sys/class/thermal / /proc/uptime
                                                            \--> HTTP GET to the LAN game-server status feed (192.168.1.111:8091)

See Chain-P/homelab for the full writeup of the Pi/homelab setup this project queries.

Related MCP server: Oraclarr

Tools

Tool

Description

system_summary()

One-shot health check: hostname, uptime, load average, disk usage, CPU temp, and every known service's status.

service_status(name)

Detailed systemd status for one service: tracker-app, coinbot, zero-bot, or zero-two.

disk_usage(path="/")

Total/used/free bytes and percent used for a filesystem path.

game_server_status()

Proxies the Windows box's existing game-server status feed (Minecraft/Zomboid/Terraria host).

service_status only accepts the four known unit names above — the MCP tool schema itself rejects anything else before the tool body ever runs.

Requirements

  • Python 3.10+ (the Pi's system Python is 3.9, hence uv below)

  • Linux with systemctl and a /sys/class/thermal/thermal_zone0/temp sensor

  • SSH key access to the host this runs on

Install & run (on the Pi)

curl -LsSf https://astral.sh/uv/install.sh | sh   # installs uv, no root needed
uv python install 3.12
git clone https://github.com/Chain-P/homelab-mcp.git
cd homelab-mcp
uv venv --python 3.12 venv
venv/bin/pip install -e .
venv/bin/homelab-mcp   # smoke test — should hang waiting on stdio, Ctrl+C to stop

Configure in an MCP client

Since the server lives on the Pi and the client runs elsewhere, invoke it over SSH:

{
  "mcpServers": {
    "homelab": {
      "command": "ssh",
      "args": ["pi@zero.local", "/home/pi/homelab-mcp/venv/bin/homelab-mcp"]
    }
  }
}

Then ask the client something like "how's the homelab doing?" or "is tracker-app running?"

Development

Tests mock every hardware/systemd dependency (subprocess.run, /sys/class/thermal/..., /proc/uptime, the game-server HTTP call), so they run identically in CI and on the Pi — no real systemd state required:

pip install -e ".[dev]"
ruff check .
pytest

Roadmap

  • Log tailing for the known services.

  • A mutating tool (restart a service) — deliberately not in v1; read-only first, gate anything that changes state separately and explicitly.

License

MIT

Available Tools

4 tools
disk_usageA

Get disk usage (total/used/free bytes, percent used) for a filesystem path on the Pi.

Inputs: path.

game_server_statusA

Get the current game-server status feed from the LAN Windows box (Minecraft/Zomboid/Terraria host).

Inputs: no named parameters.

service_statusA

Get detailed systemd status (active state, uptime, memory) for one known homelab service.

Args: name: Which service to query: tracker-app, coinbot, zero-bot, or zero-two.

Inputs: name (required).

system_summaryA

One-shot homelab health check: hostname, uptime, load average, disk usage, CPU temp, and every service's status.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 4 tools

    Disambiguation3/5

    Most tools have clear targets, but system_summary overlaps with service_status and disk_usage by bundling both into one health check. game_server_status is distinct, though it could also be considered part of the overall summary. Descriptions are clear enough to avoid serious misselection.

    Naming Consistency4/5

    All tool names use clear snake_case noun phrases like service_status, disk_usage, and game_server_status. The pattern is consistent in style, with system_summary being a slight semantic deviation but still readable and predictable.

    Tool Count4/5

    Four tools is on the smaller side but well-scoped for a focused homelab status/health server. Each tool provides a meaningful query with no redundant bloat.

    Completeness4/5

    The domain is read-only homelab monitoring, and the set covers per-service status, disk usage, game-server status, and an aggregated health summary. Logs or service controls are absent but not essential for the apparent purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      A locally-run, read-only MCP server that lets an LLM client diagnose a self-hosted *arr media stack by aggregating across Sonarr, Radarr, Prowlarr, qBittorrent, Tdarr, and Profilarr.
      76 PyPI
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Lets MCP clients (Claude Code, Claude Desktop) inspect a Linux home server's health over the network: uptime, load, memory, disk, Docker containers, systemd services, journal errors, and listening ports. Read-only, bearer-token secured.
      MIT