homelab-mcp

将 Raspberry Pi homelab 状态以 MCP 服务器的形式暴露出来——这样你就可以向 MCP 客户端（Claude Code、Claude Desktop）询问“homelab 现在怎么样？”，并直接获得真实的 systemd 服务健康状态、磁盘用量、CPU 温度以及局域网游戏服务器信息，而不是 SSH 登录进去手动检查。

按设计为只读：每个工具都只查询状态，不会执行任何重启、停止或重启动操作。

架构

服务器运行在 Pi 本身上——而不是运行 MCP 客户端的机器上——因为 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 只接受上面列出的四个已知单元名称——MCP 工具 schema 本身会在工具主体运行之前就拒绝任何其他名称。

要求

• 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

路线图

• 为已知服务增加日志 tail（尾部跟踪）功能。

• 一个会改变状态的工具（重启服务）——刻意不包含在 v1 中；以只读为先，任何改变状态的操作都要单独且明确地加以管控。

许可证

MIT