homelab-mcp

Raspberry-Pi-Homelab-Status, bereitgestellt als MCP-Server – sodass man einen MCP-Client (Claude Code, Claude Desktop) fragen kann: „Wie läuft das Homelab?“ und echte systemd-Dienstzustände, Festplattenauslastung, CPU-Temperatur und den LAN-Game-Server-Feed direkt zurückbekommt, anstatt sich per SSH einzuloggen und manuell nachzusehen.

Konzeptionell schreibgeschützt: Jedes Tool fragt lediglich Zustände ab; nichts wird neu gestartet, gestoppt oder neu gebootet.

Architektur

Weil sich die systemd-Units, die Festplatte und der Temperatursensor tatsächlich auf dem Pi befinden, läuft der Server auf dem Pi selbst – nicht auf dem Rechner, auf dem der MCP-Client läuft. Der MCP-Client erreicht ihn über SSH-getunneltes stdio: SSH stellt lediglich einen lokalen stdio-Prozess einem entfernten Client bereit, ohne dass spezielle MCP-seitige Unterstützung nötig wäre.

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)

Siehe Chain-P/homelab für die ausführliche Dokumentation des Pi-/Homelab-Setups, das dieses Projekt abfragt.

Related MCP server: Oraclarr

Tools

service_status akzeptiert nur die vier oben genannten bekannten Unit-Namen – das MCP-Tool-Schema selbst lehnt alles andere ab, bevor der Tool-Body überhaupt ausgeführt wird.

Anforderungen

• Python 3.10+ (das System-Python des Pi ist 3.9, daher uv weiter unten)

• Linux mit systemctl und einem Sensor unter /sys/class/thermal/thermal_zone0/temp

• SSH-Schlüsselzugriff auf den Host, auf dem dieses Projekt läuft

Installation & Ausführung (auf dem 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

In einem MCP-Client konfigurieren

Da der Server auf dem Pi läuft und der Client woanders, rufe ihn per SSH auf:

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

Dann frag den Client so etwas wie: „Wie läuft das Homelab?“ oder „Läuft tracker-app?“

Entwicklung

Tests mocken jede Hardware-/systemd-Abhängigkeit (subprocess.run, /sys/class/thermal/..., /proc/uptime, den HTTP-Aufruf des Game-Servers), sodass sie in CI und auf dem Pi identisch laufen – kein echter systemd-Zustand erforderlich:

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

Roadmap

• Log-Tailing für die bekannten Dienste.

• Ein Tool, das Zustände verändert (einen Dienst neu starten) – bewusst nicht in v1; zuerst nur lesend, alles, was den Zustand verändert, separat und explizit absichern.

Lizenz

MIT