homelab-mcp

Raspberry Pi 홈랩 상태를 MCP 서버로 노출합니다 — 따라서 MCP 클라이언트(Claude Code, Claude Desktop)에게 "홈랩 상태가 어떤가요?"라고 물어보면, SSH로 접속해 직접 확인하는 대신 실제 systemd 서비스 상태, 디스크 사용량, CPU 온도, LAN 게임 서버 피드를 바로 받아볼 수 있습니다.

설계상 읽기 전용입니다. 모든 도구는 상태를 조회할 뿐, 어떤 것도 재시작하거나 중지하거나 재부팅하지 않습니다.

아키텍처

서버는 MCP 클라이언트가 실행되는 머신이 아니라 Pi 자체에서 실행됩니다 — systemd 유닛, 디스크, 온도 센서가 실제로 거기 있기 때문입니다. MCP 클라이언트는 SSH 터널링된 stdio를 통해 서버에 연결합니다. 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)

이 프로젝트가 조회하는 Pi/홈랩 설정에 대한 전체 문서는 Chain-P/homelab을 참조하세요.

Related MCP server: Oraclarr

도구

service_status는 위의 네 가지 알려진 유닛 이름만 허용합니다 — MCP 도구 스키마 자체가 도구 본문이 실행되기 전에 다른 모든 것을 거부합니다.

요구 사항

• Python 3.10+ (Pi의 시스템 Python은 3.9이므로 아래의 uv를 사용합니다)

• systemctl과 /sys/class/thermal/thermal_zone0/temp 센서가 있는 Linux

• 이 서버가 실행되는 호스트에 대한 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"]
    }
  }
}

그런 다음 클라이언트에게 "홈랩 상태가 어떤가요?" 또는 "tracker-app이 실행 중인가요?"처럼 물어보세요.

개발

테스트는 모든 하드웨어/systemd 의존성을 모킹합니다 (subprocess.run, /sys/class/thermal/..., /proc/uptime, 게임 서버 HTTP 호출). 따라서 CI와 Pi에서 동일하게 실행되며, 실제 systemd 상태가 필요 없습니다:

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

로드맵

• 알려진 서비스에 대한 로그 테일링.

• 상태를 변경하는 도구(서비스 재시작) — 의도적으로 v1에는 없습니다. 읽기 전용이 우선이며, 상태를 변경하는 모든 것은 별도로 명시적으로 게이트합니다.

라이선스

MIT