homelab-mcp

Статус homelab на Raspberry Pi, доступный через MCP-сервер, — чтобы MCP-клиенту (Claude Code, Claude Desktop) можно было задать вопрос «как там homelab?» и получить в ответ реальное состояние служб systemd, использование диска, температуру CPU и ленту игрового сервера в локальной сети напрямую, вместо того чтобы заходить по SSH и проверять вручную.

Только чтение по замыслу: каждый инструмент опрашивает состояние, ничего не перезапускает, не останавливает и не перезагружает.

Архитектура

Сервер работает на самой Pi — не на машине, где запущен MCP-клиент, — ведь именно там находятся юниты systemd, диск и термодатчик. MCP-клиент подключается к нему через stdio по SSH-туннелю: SSH просто предоставляет локальный stdio-процесс удалённому клиенту, никакой специальной поддержки на стороне 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)

См. Chain-P/homelab — там полное описание настройки Pi/homelab, которую опрашивает этот проект.

Related MCP server: Oraclarr

Инструменты

service_status принимает только четыре известных имени юнитов из списка выше — сама схема MCP-инструмента отклоняет всё остальное ещё до выполнения тела инструмента.

Требования

• Python 3.10+ (системный Python на Pi — 3.9, поэтому ниже используется uv)

• Linux с systemctl и датчиком /sys/class/thermal/thermal_zone0/temp

• Доступ по SSH-ключу к хосту, на котором это запускается

Установка и запуск (на 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

Настройка в MCP-клиенте

Поскольку сервер живёт на Pi, а клиент работает в другом месте, вызывайте его через SSH:

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

Затем спросите клиента, например: «как там homelab?» или «запущен ли tracker-app?»

Разработка

В тестах замоканы все зависимости от железа и systemd (subprocess.run, /sys/class/thermal/..., /proc/uptime, HTTP-вызов игрового сервера), поэтому они работают одинаково в CI и на Pi — реальное состояние systemd не требуется:

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

Дорожная карта

• Просмотр «хвоста» логов известных служб.

• Изменяющий инструмент (перезапуск службы) — намеренно не в v1: сначала только чтение, а всё, что меняет состояние, — за отдельным явным разрешением.

Лицензия

MIT