让你的AI助手访问任何地方的工具,无论它们在哪里运行
BetterHub 是一个创新的 MCP (Model Context Protocol) 反向代理系统,解决了 AI 助手无法直接访问 NAT 后面或远程设备上工具的问题。通过巧妙的反向连接架构,BetterHub 让 Claude Desktop 能够安全地访问运行在任何地方的 MCP 服务器 - 无论是你的家庭服务器、办公室电脑,还是云端实例。
- 🌐 NAT 穿透:无需端口映射,支持双方都在 NAT 后面
- 🔐 安全连接:基于 UUID 的设备认领机制
- 🚄 高性能:WebSocket 长连接,低延迟通信
- 🔧 易于部署:简单的配置,开箱即用
- 📦 多服务器支持:一个连接器管理多个 MCP 服务器
- 🏗️ 灵活架构:支持 stdio、HTTP、SSE 等多种 MCP 协议
- 🏷️ 设备命名:为设备设置友好名称,工具自动添加前缀
- 👥 多设备管理:一个用户可以管理多个设备的所有工具
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Claude Desktop │ │ BetterHub │ │ Remote Device │
│ │ │ (公网服务器) │ │ │
│ reverse- │ HTTP │ │ WebSocket│ mcp-hub- │
│ connector ├────────►│ Hub Server │◄──────────┤ connector │
│ (虚拟MCP) │ │ (中继&路由) │ │ (设备代理) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
NAT A Internet NAT B
- 设备注册:远程设备上的 connector 通过 WebSocket 连接到 Hub
- 设备认领:用户通过 UUID 认领设备,建立所有权关系
- 请求转发:Claude 发起的 MCP 请求通过 reverse-connector 转发到 Hub
- 智能路由:Hub 根据工具名称路由请求到正确的设备和 MCP 服务器
- 响应返回:MCP 服务器的响应原路返回给 Claude
project_docs/
├── 1-需求与功能.md # 项目需求和功能说明
├── 2-系统架构.md # 架构设计和核心组件
├── 3-API接口.md # 完整的 API 参考
└── 4-测试报告.md # 测试结果和已知问题
betterhub/
├── betterhub-server/ # Hub 服务器
│ └── src/
│ ├── hub-v2.ts # 主服务器实现
│ └── types.ts # 类型定义
├── mcp-hub-connector/ # 设备端连接器
│ └── src/
│ ├── connector-v2.ts # 连接器主程序
│ ├── mcp-manager.ts # MCP 服务器管理
│ └── config.ts # 配置加载
├── mcp-hub-reverse-connector/ # 客户端连接器
│ └── src/
│ ├── multi-device-reverse.ts # 多设备支持
│ └── index.ts # 单设备版本
│ │
│ ├── reverse-connector/ # Claude 端虚拟 MCP 服务器
│ │ ├── index.ts # 主程序入口
│ │ ├── api-client.ts # Hub API 客户端
│ │ └── types.ts # TypeScript 类型定义
│ │
│ ├── hub/ # 中央 Hub 服务器
│ │ ├── server.ts # Express 服务器主程序
│ │ ├── websocket.ts # WebSocket 连接管理
│ │ ├── database.ts # SQLite 数据库操作
│ │ ├── routes/ # REST API 路由
│ │ │ ├── device.ts # 设备管理相关接口
│ │ │ └── user.ts # 用户管理相关接口
│ │ └── types.ts # TypeScript 类型定义
│ │
│ └── shared/ # 共享代码
│ ├── protocol.ts # MCP 协议定义
│ └── utils.ts # 工具函数
│
├── dist/ # 编译输出目录
│ └── [编译后的 JS 文件]
│
├── scripts/ # 脚本目录
│ ├── setup.sh # 环境初始化脚本
│ └── deploy.sh # 部署脚本
│
├── config/ # 配置文件目录
│ ├── connector.example.json # 连接器配置示例
│ └── hub.example.json # Hub 配置示例
│
├── tests/ # 测试文件
│ ├── unit/ # 单元测试
│ └── integration/ # 集成测试
│
├── docs/ # 文档目录
│ ├── API.md # API 文档
│ ├── ARCHITECTURE.md # 架构设计文档
│ └── DEPLOYMENT.md # 部署指南
│
├── sample-mcp-hub-main/ # 参考项目 1(只读)
├── sample-mcphub-main/ # 参考项目 2(只读)
│
├── package.json # 项目依赖和脚本
├── tsconfig.json # TypeScript 配置
├── .env.example # 环境变量示例
├── .gitignore # Git 忽略配置
├── LICENSE # MIT 许可证
├── CLAUDE.md # Claude AI 开发指南
└── README.md # 本文档
设备端连接器,负责:
- 建立和维护与 Hub 的 WebSocket 连接
- 管理本地 MCP 服务器进程
- 转发 MCP 请求和响应
- 设备 UUID 管理和持久化
Claude 端虚拟 MCP 服务器,负责:
- 实现标准 MCP 服务器协议(stdio)
- 通过 HTTP API 与 Hub 通信
- 设备认领和连接管理
- 动态能力发现和聚合
中央 Hub 服务器,负责:
- 管理所有设备连接
- 用户认证和设备授权
- 消息路由和转发
- REST API 和 WebSocket 服务
共享代码库,包含:
- MCP 协议类型定义
- 通用工具函数
- 常量定义
- Node.js 18+
- npm 或 yarn
- SQLite3(Hub 服务器)
git clone https://github.com/yourusername/betterhub.git
cd betterhubnpm installnpm run build# 复制并编辑配置文件
cp config/hub.example.json config/hub.json
# 设置环境变量
cp .env.example .env
# 编辑 .env 文件,设置 JWT_SECRET 等
# 启动 Hub 服务器
npm run start:hub在拥有 MCP 服务器的设备上:
# 复制并编辑配置文件
cp config/connector.example.json config/connector.json
# 编辑配置文件,添加本地 MCP 服务器信息
{
"hubUrl": "wss://your-hub-server.com",
"servers": [
{
"name": "filesystem",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user"]
}
]
}
# 启动 Connector
npm run start:connector编辑 Claude Desktop 配置文件:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"betterhub": {
"command": "node",
"args": ["/path/to/betterhub/dist/reverse-connector/index.js"],
"env": {
"BETTERHUB_API_URL": "https://your-hub-server.com/api",
"BETTERHUB_DEVICE_UUID": "your-device-uuid"
}
}
}
}Connector 首次启动时会生成 UUID:
$ npm run start:connector
[INFO] Generated new device UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
[INFO] Connecting to hub: wss://hub.example.com
[INFO] Connected successfully在 Claude 中使用设备前,需要先认领:
# 通过 API 认领设备
curl -X POST https://hub.example.com/api/devices/claim \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"deviceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'认领成功后,重启 Claude Desktop,即可看到远程设备上的所有 MCP 工具。
{
"port": 3000,
"database": {
"path": "./data/hub.db"
},
"websocket": {
"heartbeatInterval": 30000,
"maxReconnectAttempts": 5
},
"security": {
"jwtExpiry": "7d",
"bcryptRounds": 10
}
}{
"hubUrl": "wss://hub.example.com",
"deviceName": "Home Server",
"reconnectInterval": 5000,
"servers": [
{
"name": "filesystem",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home"],
"protocol": "stdio"
},
{
"name": "github",
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_TOKEN": "your-token"
}
}
]
}BetterHub 支持一个 Connector 管理多个 MCP 服务器,自动添加命名空间避免冲突:
// 原始工具名:search
// 转换后:filesystem__search, github__searchConnector 内置自动重连机制,网络中断后会自动恢复连接。
即将支持的功能:
- 设备分组管理
- 基于角色的访问控制
- 设备共享
- 端到端加密:所有通信使用 TLS 加密
- 身份验证:基于 JWT 的用户认证
- 设备授权:UUID 认领机制确保设备所有权
- 访问控制:用户只能访问自己认领的设备
欢迎贡献代码!请遵循以下步骤:
- Fork 项目
- 创建功能分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 开启 Pull Request
本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。
- Model Context Protocol - Anthropic 的 MCP 协议
- sample-mcp-hub - 参考实现
- 所有贡献者和用户
- 项目主页:https://github.com/yourusername/betterhub
- Issue 追踪:GitHub Issues
- 讨论区:GitHub Discussions
BetterHub - 连接你的 AI 助手与整个世界 🌍