homelab-mcp

Raspberry Pi homelab の状態を MCP サーバーとして公開します。つまり、MCP クライアント (Claude Code、Claude Desktop) に「homelab の調子はどう?」と尋ねるだけで、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/homelab 構成の詳細な解説については、Chain-P/homelab を参照してください。

Related MCP server: Oraclarr

ツール

service_status は上記の既知の 4 つのユニット名のみを受け付けます。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"]
    }
  }
}

次に、クライアントに「homelab の調子はどう?」や「tracker-app は動いている?」などと尋ねます。

開発

テストはすべてのハードウェア/systemd 依存関係 (subprocess.run、/sys/class/thermal/...、/proc/uptime、ゲームサーバーの HTTP 呼び出し) をモックするため、CI と Pi の両方で同じように実行されます。実際の systemd の状態は必要ありません:

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

ロードマップ

• 既知のサービスのログテーリング。

• 変更を加えるツール (サービスの再起動) — 意図的に v1 には含めていません。まず読み取り専用にし、状態を変更するものは別途、明示的にゲートします。

ライセンス

MIT