Skip to main content
Glama

MCP Hub

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

Release License: MIT Python 3.11+ MCP CI

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 支持三种执行模式:

模式

预期用途

命令

支持级别

可编辑包

开发和贡献

pip install -e ".[dev]" 然后 mcp-hub

支持开发用途

直接源码执行

快速本地评估

python server.py

支持,操作员管理进程

systemd 安装

持久化家庭实验室部署

sudo ./deploy/install.sh

推荐用于生产环境

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 模板:

文件

用途

必需

.env

端口、认证、功能标志、API 令牌

是

hosts.yaml

设备清单:主机名、用户、角色、标签

是

topology.yaml

策划覆盖:访客映射、回收 IP 陷阱、勿动列表

否

endpoints.yaml

用于 endpoints_health 的 HTTP 健康探测

否

主机条目设计为最小化:

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 中有文档说明;限制拒绝使用与所有其他调用相同的响应信封和审计轨迹。

分组

工具

集群与 Shell

list_hosts topology get_topology system_info get_system_info remote_exec local_exec fleet_exec batch_exec read_file service_ctl journal_query get_journal_entries apt_status list_package_updates ssh_reset_control wake_host dhcp_reservations endpoints_health infra_snapshot destroy_resource

Proxmox 与容器

proxmox_list list_proxmox_guests proxmox_ct_status proxmox_ct_exec ct_exec ct_write_file pbs_status docker_ps list_docker_containers docker_exec

Synology DSM

dsm_health dsm_system_info dsm_storage dsm_shares dsm_packages dsm_package_control dsm_updates dsm_connections dsm_logs dsm_power dsm_file_list dsm_file_search dsm_download_list dsm_download_create dsm_download_control dsm_api dsm_relogin

Cloudflare

cloudflare_tunnels_list list_cloudflare_tunnels cloudflare_tunnel_get cloudflare_tunnel_config_get cloudflare_tunnel_config_update cloudflare_dns_list cloudflare_dns_create cloudflare_dns_delete cf_ingress_dump get_cloudflare_tunnel_ingress cloudflare_api

n8n

n8n_health n8n_list_workflows n8n_get_workflow n8n_activate_workflow n8n_deactivate_workflow n8n_list_executions n8n_get_execution n8n_call_webhook

Notion

notion_search notion_get_page notion_create_page notion_update_page notion_archive_page notion_query_database notion_get_block_children notion_append_blocks notion_append_table_row notion_delete_block notion_reload_token

Vault

vault_search vault_get_item vault_get_field vault_create_item vault_update_item vault_list_folders

LM Studio

lmstudio_status lmstudio_load lmstudio_unload

Ollama

ollama_status ollama_generate ollama_embed ollama_pull ollama_unload

Qdrant

qdrant_collections qdrant_search qdrant_upsert

引导式诊断

diagnose_service diagnose_endpoint audit_host check_backup_chain

任务与自省

job_run job_status job_list job_logs mcp_health get_mcp_health mcp_stats get_mcp_stats audit_export plan_mutation confirm_mutation rollback_change

完整的 生成工具参考 将每个分组扩展为一个表格,包含每个工具的精确签名和面向模型的描述。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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP server for full Home Assistant control, enabling AI agents to manage dashboards, automations, files, apps, entities, and more via REST API, WebSocket, and SSH.
      66
      151 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that gives AI assistants real-time access to your homelab infrastructure. It enables querying node status, managing Docker containers, controlling Proxmox VMs, and inspecting OPNsense firewall state through natural conversation.
      51 PyPI
      2
      MIT