MCP Hub

一个 MCP 服务器，让你的 AI 助手掌握整个家庭实验室的钥匙。

MCP Hub 是一个单一的 Model Context Protocol 服务器，部署在网络中的一台机器上，并从那里向外辐射：通过 SSH 连接到你的所有主机、Proxmox 容器、Docker、Synology DSM、Cloudflare 隧道和 DNS、n8n 工作流、Notion、你的密码库。你无需运行十几个 MCP 服务器并将每个都接入客户端，只需运行一个，然后将你的 AI 助手指向它。

“为什么 Jellyfin 连不上了？” —— 助手检查容器，读取日志，发现隧道入口已失效，修复它，然后告诉你它做了什么。

⚠️ 在部署之前，请阅读 SECURITY.md。 MCP Hub 将 LLM 的 root shell 访问权限交予你的整个设备群。这正是它的目的，但也确实危险。默认设置是安全的（127.0.0.1，只读）；当你更改它们时，危险就开始了。

故障排除演示

该仓库包含一个经过清理的 Asciinema 录制，展示了一个完整的、以观察为先的故障排除会话：故障端点、systemd 诊断、精确的变更计划、明确确认、重启以及最终的健康检查。它使用了示例清单，不包含任何私有基础设施数据。

asciinema play docs/troubleshooting.cast

当未安装 Asciinema 时，请直接查看录制文件；该 cast 格式是换行符分隔的 JSON，仍然可审查。

Related MCP server: homelab-mcp

目录

• 功能特性

• 快速开始

• 部署

• 本地测试

• 救援诊断

• 配置

• 工具参考

• 安全

• 版本管理

• 贡献

功能特性

• 111 个工具，一个端点，一个配置文件。

• 配置驱动。 你的网络存在于 hosts.yaml 和 .env 中。你的基础设施信息不会硬编码到代码中。

• 多路复用 SSH。 持久化控制套接字，因此对整个设备群的命令只需毫秒级时间，而不是每次进行 TCP 握手。

• 可选集成。 每个集成默认关闭，只需一个标志即可启用。如果你只需要纯粹的 SSH 设备群工具，就这样运行它。

• 可插拔的密钥。 从环境变量或通过 bw serve 从 Bitwarden/Vaultwarden 密码库读取凭据。

• Bearer 令牌认证，基于一个不可猜测的端点路径。

• 全局只读模式，默认开启：一个标志即可禁用所有 43 个可变工具，集中执行而非逐个工具执行。

• 自动密钥脱敏，在文件读取和命令输出中生效。

• 后台任务，支持轮询、日志和持久化 SQLite 状态存储。

快速开始

需要 Python 3.11+ 和一个能够 SSH 访问你要管理机器的 Linux 主机。

git clone https://github.com/wnx82/mcp-hub.git
cd mcp-hub

python3 -m venv .venv && . .venv/bin/activate
pip install -e .

cp .env.example .env                  # then edit — see below
cp hosts.example.yaml hosts.yaml      # then edit: your fleet
chmod 600 .env hosts.yaml

python server.py

至少，在 .env 中设置以下两项：

MCP_SECRET_PATH=/$(openssl rand -hex 16)   # unguessable endpoint path
MCP_AUTH_TOKEN=$(openssl rand -hex 32)     # bearer token — the real auth

然后服务器会在 http://127.0.0.1:8000<MCP_SECRET_PATH> 上监听，并设置 MCP_READ_ONLY=true。将你的 MCP 客户端指向该 URL，并发送 Authorization: Bearer <MCP_AUTH_TOKEN>。没有令牌的请求会收到 401；访问其他路径的请求会收到 404。

对于需要 stdio 而非 HTTP 的本地 MCP 客户端，请使用以下命令启动相同的 Hub：

mcp-hub --transport stdio

或者在启动前在环境中设置 MCP_TRANSPORT=stdio。

对于 systemd 部署，sudo ./deploy/install.sh 会创建一个专用的 mcphub 用户和 SSH 密钥，将两个密钥生成到 /etc/default/mcp-hub 中，并安装服务单元。它是幂等的，不会覆盖现有配置。请参阅 deploy/。

关于完整的 Claude Code 设置、安全的令牌处理、连接检查、首次只读提示以及当前的 Claude Desktop 限制，请参阅 将 MCP Hub 连接到 Claude。

如果你希望你的助手了解你的私有拓扑、主机角色、变更窗口和 MCP 操作规则，但又不想提交这些数据，请从 PROJECT_INSTRUCTIONS.example.md 开始，并将你自定义的 PROJECT_INSTRUCTIONS.md 保留在本地。

部署

MCP Hub 支持三种执行模式：

Python 包和直接执行使用当前的检出目录及其虚拟环境。它们不会创建服务账户、SSH 密钥、环境文件或重启策略。systemd 安装程序会配置这些操作组件，在重新运行时保持本地配置不变，并在 Hub 虚拟环境之外安装 Rescue。

容器镜像目前不是官方部署目标。Hub 需要网络访问、SSH 身份、持久化的 state.db 以及对其本地清单的访问；将其打包到容器中的操作员必须自行维护这些属性。

请参阅 docs/docker-packaging.md 了解当前要求，以及官方镜像在可被推荐之前需要保证的内容。

本地测试

关于面向贡献者的检查清单，涵盖 lint、单元测试、工具注册、生成的文档、安装程序冒烟测试以及手动只读运行，请参阅 docs/testing-local.md。

关于 MCP 2026-07-28 迁移摘要、兼容性矩阵和回滚流程，请参阅 docs/migration/mcp-2026-07-28-guide.md。

在提交 PR 或发布分支之前，你也可以运行本地发布就绪检查：

python3 scripts/check_repo_hygiene.py
python3 scripts/check_tool_annotations.py
python3 scripts/check_security_readiness.py

要在推送时自动将安全就绪检查接入 Git：

./scripts/install_pre_push_hook.sh

架构

server.py 仍然是 MCP 服务器的组合根，而领域代码正在逐步迁移到 tools/ 中。SSH 命令构建、Cloudflare 路径和响应提取、DSM 协议元数据、清单和剧本构建器已经隔离。tools/registry.py 将提取的工具分配给一个领域；该领域包含在每个审计摘要中。新的协议逻辑应位于其领域模块中，并且不得导入 server.py。

未来集成的优先级在 docs/integration-evaluation.md 中列出，包括它们的最小权限范围和升级门控。

救援诊断

mcp-hub-rescue 是一个只读的本地 CLI，设计用于在主服务器无法导入或其虚拟环境损坏时继续工作。systemd 安装程序会将其复制到 /opt/mcp-hub-rescue，并使用系统 Python（在 MCP Hub 进程和虚拟环境之外）运行它。

sudo mcp-hub-rescue doctor
sudo mcp-hub-rescue status
sudo mcp-hub-rescue health
sudo mcp-hub-rescue logs --lines 50
sudo mcp-hub-rescue validate-config

结果是结构化的 JSON。Rescue 从不导入 server.py、tools/*、MCP 或任何可选集成，并且此边界由 CI 强制执行。当前命令仅用于观察和诊断；重启、修复和回滚操作将单独添加，并带有确认和最后已知良好状态保护。

配置

所有文件都被 git 忽略——每个文件都有一个被跟踪的 .example 模板：

主机条目设计为最小化：

hosts:
  nas:
    hostname: nas.example.lan
    user: admin
    role: storage
    tags: [nas, backup]
    mac: "aa:bb:cc:dd:ee:01"   # optional, enables wake_host()

标签用于寻址组：fleet_exec(tag="backup", command="df -h")。对于可直接复制的双主机清单，请从 docs/examples/hosts.minimal.yaml 开始。更大的 hosts.example.yaml 演示了所有支持的主机选项。

将其与 docs/examples/topology.guarded.yaml 配对，以映射 Proxmox 访客、记录过时地址陷阱，并标记不应随意更改的基础设施。_do_not_touch 条目是助手的操作上下文，而非强制访问控制边界；请使用令牌配置文件和主机限制进行技术性强制执行。

添加 docs/examples/endpoints.minimal.yaml 以监控始终在线和间歇性的 HTTP 服务。调用 endpoints_health() 获取常规集合，或调用 endpoints_health(include_intermittent=true) 以包含可能通常已关闭的服务。200 到 399 的响应视为健康；不跟踪重定向。

完整的默认值、限制、集成设置和密钥处理说明位于 环境变量参考 中。

将这些被跟踪的示例与一个私有的、未被跟踪的 PROJECT_INSTRUCTIONS.md 配对，以便你的助手了解拓扑注意事项、维护窗口、命名约定以及不应存在于仓库中的“请勿触碰”指南。

工具参考

每个工具返回相同的顶层信封：

{
  "ok": true,
  "data": {},
  "error": null,
  "duration_ms": 12,
  "host": "example",
  "request_id": "4d52b1f69b974b7784bf65dd",
  "tool": "system_info"
}

data 包含工具特定的负载。安全拒绝和受控异常使用相同的结构，并带有 ok: false，使得链式调用和审计关联可预测。

中央工具包装器还限制了请求大小、每个令牌的调用次数、每个目标的并发调用次数、重复的目标失败次数以及变更频率。默认值在 .env.example 中有文档说明；限制拒绝使用与所有其他调用相同的响应信封和审计轨迹。

完整的 生成工具参考 将每个分组扩展为一个表格，包含每个工具的精确签名和面向模型的描述。CI 会对照注册的函数对其进行检查。

引导式诊断总是在观察后停止。它们返回证据、评估和建议的下一步操作，并带有 correction_applied: false；check_backup_chain 是一个新鲜度和存储信号，而不是恢复将成功的证明。

安全

MCP Hub 设计上是一个远程代码执行服务。在将其暴露之前：

• 保留默认的 127.0.0.1 绑定，或将其放在带有访问策略的隧道后面。

• 设置 MCP_AUTH_TOKEN —— 秘密 URL 路径是混淆，而不是认证。

• 保持 MCP_READ_ONLY=true，直到你信任你的模型如何处理它。

• 保持资源防护默认启用，然后根据观察到的审计流量进行调整，而不是禁用它们。

• 为其分配专用的 SSH 密钥和最简的 hosts.yaml。

完整的威胁模型、强化指南和漏洞报告： SECURITY.md。

关于发布前的本地检查表和可选的 Git 钩子，用于在推送前捕获常见的秘密泄露错误，请参见 scripts/check_security_readiness.py 和 scripts/install_pre_push_hook.sh。

版本控制

SemVer。在 1.0 之前，破坏性变更提升 minor —— 所以在升级一个版本之前请阅读 Changed 和 Removed 说明。 _version.py 是唯一真理来源；运行中的服务器通过 mcp-hub --version、在 MCP 握手期间以及在 mcp_health 中报告它。

每个版本都记录在 CHANGELOG.md 中，与安全相关的变更在其自己的部分中专门指出。

贡献

欢迎提交问题和拉取请求 —— 特别是 bug 报告、新集成和文档修复。请参阅 CONTRIBUTING.md。

许可证

MIT © wnx82