homelab-mcp

Estado del homelab en Raspberry Pi, expuesto como un servidor MCP, para que un cliente MCP (Claude Code, Claude Desktop) pueda recibir la pregunta «¿cómo está el homelab?» y obtener el estado real de los servicios systemd, el uso de disco, la temperatura de la CPU y el feed del servidor de juegos de la LAN directamente, en lugar de entrar por SSH y comprobarlo a mano.

De solo lectura por diseño: cada herramienta consulta el estado; ninguna reinicia, detiene ni rearranca nada.

Arquitectura

El servidor se ejecuta en la propia Pi — no en la máquina que ejecuta el cliente MCP —, ya que es ahí donde están realmente las unidades de systemd, el disco y el sensor térmico. El cliente MCP se conecta a él mediante stdio por túnel SSH: SSH simplemente expone un proceso stdio local a un cliente remoto, sin necesidad de soporte especial en el lado de MCP.

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)

Consulta Chain-P/homelab para ver la descripción completa de la configuración de la Pi/homelab que este proyecto consulta.

Related MCP server: Oraclarr

Herramientas

service_status solo acepta los cuatro nombres de unidad conocidos anteriores — el propio esquema de la herramienta MCP rechaza cualquier otra cosa antes de que el cuerpo de la herramienta llegue a ejecutarse.

Requisitos

• Python 3.10+ (el Python del sistema de la Pi es 3.9, de ahí uv más abajo)

• Linux con systemctl y un sensor /sys/class/thermal/thermal_zone0/temp

• Acceso por clave SSH al host donde se ejecuta

Instalar y ejecutar (en la 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

Configurar en un cliente MCP

Dado que el servidor reside en la Pi y el cliente se ejecuta en otra máquina, invócalo por SSH:

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

Después pregúntale al cliente algo como «¿cómo está el homelab?» o «¿está corriendo tracker-app?».

Desarrollo

Los tests simulan todas las dependencias de hardware/systemd (subprocess.run, /sys/class/thermal/..., /proc/uptime, la llamada HTTP al servidor de juegos), por lo que se ejecutan de forma idéntica en CI y en la Pi — no se requiere estado real de systemd:

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

Hoja de ruta

• Seguimiento de logs de los servicios conocidos.

• Una herramienta mutadora (reiniciar un servicio) — deliberadamente fuera de la v1; primero solo lectura, y cualquier cosa que cambie el estado debe restringirse por separado y explícitamente.

Licencia

MIT