samanhappy/mcphub · 上手攻略

• 仓库：samanhappy/mcphub
• 链接：https://github.com/samanhappy/mcphub
• 分类：AI Infrastructure / MCP Gateway
• 作者：Tom
• 更新：2026-10-08

---

一、是什么

MCPHub 是一个自托管的 MCP（Model Context Protocol）网关与控制平面，为 AI 客户端和 MCP 服务器之间提供统一的接入点。它的核心角色是：把散落在各处的本地或远程 MCP 服务器，通过一个稳定的网关出口暴露给 AI 客户端（如 Claude Code、Cursor、Cherry Studio、OpenWebUI 等），同时在这一层统一完成认证、鉴权、流量调度和可观测。

GitHub Stars 约 2503（数据来源于 2026-10-08 工作队列）。⚠️ Stars 数字未实时核验，仅供参考。

---

二、解决什么问题

在 MCP 生态中，每个 MCP 服务器通常需要独立配置、独立端口、独立凭证。当团队需要共用一批 MCP 能力（如浏览器自动化、地图、Slack 集成）时：

• 没有网关：每个 AI 客户端各自直连，凭证分散，无法统一管控。
• 使用 MCPHub：所有服务器注册到 Hub，AI 客户端只连 Hub 一个地址，按路由规则（按服务器、按组、按智能路由）访问能力，凭证由 Hub 集中管理并以 per-user 方式绑定。

此外，对于需要向多人暴露同一 MCP 服务器但各自使用自己 API Key 的场景（如 Tavily、Context7 等付费服务），MCPHub 的 Per-user Credentials 功能可以在不暴露服务器配置的情况下，让每个用户绑定自己的密钥。

---

三、快速安装

Docker（推荐）

一行命令启动，默认使用文件存储：

docker run -p 3000:3000 -v $(pwd)/data:/app/data samanhappy/mcphub

首次启动若未设置 ADMIN_PASSWORD，随机密码会打印在容器日志中。预置密码方式：

docker run -p 3000:3000 -v $(pwd)/data:/app/data \
  -e ADMIN_PASSWORD=your-secure-password samanhappy/mcphub

⚠️ 首次登录后请立即修改 admin 密码。

npm 全局安装

npm install -g @samanhappy/mcphub
mcphub

从源码运行（需 Node.js ≥20.0.0 + pnpm 10.12.4）

git clone https://github.com/samanhappy/mcphub.git
cd mcphub
pnpm install
pnpm dev

本地开发模式默认账号：admin / admin123。

---

四、核心配置

添加第一个 MCP 服务器（mcp_settings.json）

在 ./data/mcp_settings.json 中声明服务器，支持 stdio / SSE / Streamable HTTP / OpenAPI 四种传输类型：

{
  "mcpServers": {
    "fetch": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["@playwright/mcp@latest", "--headless"]
    },
    "amap": {
      "type": "sse",
      "url": "https://mcp.amap.com/sse?key=YOUR_KEY"
    }
  }
}

AI 客户端接入端点

Hub 启动后，AI 客户端通过以下端点接入：

端点	含义
http://localhost:3000/mcp	全部服务器
http://localhost:3000/mcp/{group}	指定分组
http://localhost:3000/mcp/{server}	单个服务器
http://localhost:3000/mcp/$smart	智能路由（需 PostgreSQL + pgvector + LLM API Key）

Per-user Credentials（每用户独立凭证）

将付费服务的 API Key 从「共享」变成「个人绑定」，服务器配置者只声明槽位，用户各自填入自己的密钥，密钥加密存储在 Hub 侧：

{
  "mcpServers": {
    "tavily": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tavily-mcp"],
      "credentialTemplate": [
        { "target": "env", "name": "TAVILY_API_KEY", "label": "Tavily API key" }
      ]
    }
  }
}

⚠️ ⚠️ 凭证密钥文件（*.credentials.key）不随 Docker 镜像走，需同步备份；多实例共享数据库时必须使用同一个加密密钥。

生产级：数据库模式

文件模式适合个人或小团队；生产环境推荐 PostgreSQL + pgvector（用于 Smart Routing 向量检索）：

docker run -d \
  -p 5432:5432 \
  -e POSTGRES_PASSWORD=secret \
  -e POSTGRES_USER=mcpuser \
  -e POSTGRES_DB=mcpdb \
  -v pgdata:/var/lib/postgresql/data \
  postgres:16 \
  -c "shared_preload_libraries=vector"

⚠️ 数据库迁移参考官方文档（docs.mcphub.app/configuration/database-configuration），文件→数据库迁移时需保留加密密钥。

两种 Docker 镜像

镜像标签	内容
latest（默认）	Node.js/pnpm + Python + uv/uvx + Git + 构建工具，覆盖大多数 MCP 服务器
latest-full	额外增加 Rust 工具链（cargo/rustc）+ Docker Engine + Playwright（Chrome + Firefox，amd64），用于 Rust 基础服务器或容器内再跑容器

---

五、典型使用场景

1. 团队 MCP 能力共享：管理员配好服务器清单，团队成员各自接入 Hub，按需绑定个人 API Key，无需每个人各自配置服务器环境。
2. AI 客户端统一接入：Claude Code、Cursor 等客户端只需配置一个 Hub 端点，按路由访问所有已注册的 MCP 能力。
3. 智能工具发现（Smart Routing）：启用 PostgreSQL + pgvector 后，AI 客户端通过自然语言描述任务，Hub 自动向量检索最相关的工具并暴露，减少手动选工具的负担。
4. 企业级访问控制：通过 OAuth 2.0（支持 GitHub/Google 社交登录）、Bearer Key、服务器可见性控制，实现精细的权限管理。
5. MCP Apps 透明代理：交互式 MCP Apps（如需要特殊握手的应用）在单服务器路由上可透明转发。

---

六、坑与注意

1. 首次启动密码：若未设置 ADMIN_PASSWORD，随机密码在容器日志里，需及时查看并记录。日志命令：docker logs <container>。
2. 凭证密钥持久化：Docker 运行时务必挂载 ./data 目录，否则 *.credentials.key 文件丢失后已加密的凭证无法恢复。
3. Bearer 认证默认开启：MCP 端点默认需要认证，防止意外暴露。在 Keys 页面可关闭（仅限可信内网环境）。⚠️ 关闭后所有端点无需 Key 即可访问。
4. Smart Routing 额外依赖：使用 $smart 端点需要 PostgreSQL + pgvector + OpenAI 或兼容 LLM API Key，不是开箱即用的功能。
5. ADMIN_PASSWORD 只在首个用户创建前生效：用户列表非空后该环境变量被忽略，修改密码需通过 dashboard 或 API。
6. 最新镜像含构建工具但不含数据库：需自行准备 PostgreSQL（Smart Routing 必需）或只用文件模式。
7. Windows 开发模式：需分别运行 pnpm backend:dev（端口 3000）和 pnpm frontend:dev（端口 5173），两者不能合并启动。

---

七、与同类对比

维度	MCPHub（本篇）	Docker MCP Gateway	Solo.io Agent Gateway	Portkey MCP
部署方式	自托管 / Docker	Docker Compose	Kubernetes / 云	SaaS + 自托管
Per-user 凭证	✅ 原生支持（加密存储）	❌ 不支持	有限	✅ 通过 LLM gateway
Smart Routing	✅ 向量语义搜索（pgvector）	❌	❌	✅（通过 LLM gateway）
OAuth / 社交登录	✅（GitHub / Google + Better Auth）	❌	✅	✅
开源	✅ Apache 2.0	✅	✅	❌（闭源为主）
适合规模	个人 / 小团队 / 中型团队	个人 / 小团队	企业	已用 Portkey 的团队
上手难度	低（Docker 一行）	极低	高（K8s 门槛）	中（SaaS 接入简单）

MCPHub 的核心差异化在于原生 per-user credentials 和开源自托管的组合，适合不想把所有数据交给第三方、又不希望自己从零搭网关的团队。相比 Docker 官方方案多了用户体系和智能路由；相比企业级方案（Solo.io、Portkey）上手门槛低得多。

---

八、一句话推荐结论

如果你在团队中需要让多个人共用一批 MCP 工具、且各自绑定自己的 API Key，MCPHub 是目前开源方案里 per-user credentials 支持最完整、上手最快（Docker 一行） 的选择。 如果仅需本地单用户快速接入 Docker 官方 MCP Catalog，直接用 Docker MCP Gateway 更简单；如果需要企业级服务网格和深度定制，Solo.io Agent Gateway 更合适。