MCPHub: The Unified Hub for Model Context Protocol (MCP) Servers

MCPHub

一个开源、可自托管的 MCP 网关和控制平面，用于连接、控制和运维 MCP 服务。

English | Français | 中文版

MCPHub 在 AI 客户端与 MCP 服务之间提供统一的控制点。只需连接一次本地和远程 MCP 服务，即可通过稳定的端点组织和路由它们的能力；借助身份验证、受限凭据和按用户控制的可见性管理访问权限；并通过集中式日志、活动跟踪和健康监控来运维所有服务。

它兼容 Claude Code、Cursor、Cherry Studio、OpenWebUI 等 MCP 客户端，以及其他兼容 MCP 的应用。

🌐 网站、演示与文档

• 网站：mcphub.app
• 文档：docs.mcphub.app
• 演示环境：demo.mcphub.app

🚀 功能

一次连接，随处接入

• 智能路由 ⭐ - 使用向量语义搜索发现工具，由 AI 提供支持（了解更多）
• 统一 MCP 网关 - 通过稳定的 MCP 端点公开所有已连接的服务，包括群组和单个服务的路由
• 服务别名与路由 - 定义别名，并将客户端路由到所有服务、特定群组、单个服务或智能路由
• 支持 SSE / Streamable HTTP / stdio - 通过支持的传输方式连接本地和远程 MCP 服务
• 热切换配置 - 无需停机即可添加、移除或更新服务

控制访问权限和凭据

• 按用户配置凭据 ⭐ - 将个人密钥绑定到一个共享服务，并支持加密存储和隔离的 stdio 运行时（了解更多）
• 身份验证与访问控制 - 使用 OAuth 2.0、Bearer 密钥，以及服务或群组可见性控制来管理访问权限
• 支持 OAuth 2.0 ⭐ - 同时支持客户端和服务端模式，实现安全身份验证（了解更多）
• 社交登录 - 通过 Better Auth 集成，支持便捷的 GitHub 和 Google 登录（需要数据库模式）
• 服务与群组管理 - 将服务整理到群组中，管理可见性，并控制工具、提示词和资源的公开范围

安心运维

• 日志与可观测性 - 查看工具调用活动、请求状态、延迟和服务日志
• 健康检查 - 在一个位置监控连接健康状况和服务状态
• Web 控制面板 - 通过浏览器管理服务配置和运行时操作
• MCP Apps 代理 - 在单服务路由上透明转发交互式 MCP Apps（了解更多）
• 工具结果压缩 - 在大型文本工具输出到达客户端前，透明地对其进行压缩
• 数据库模式 - 在 PostgreSQL 中存储配置，适用于生产环境（了解更多）
• 适配 Docker - 通过容器化设置快速部署

🔧 快速开始

前置条件

• Docker（推荐）——运行 MCPHub 的最快方式；以下命令均使用 Docker
• Node.js >=20.0.0 和 pnpm 10.12.4 ——仅在从源代码运行或本地开发时需要（参见本地开发）

使用 Docker 启动

docker run -p 3000:3000 -v ./data:/app/data samanhappy/mcphub

打开 http://localhost:3000，并使用用户名 admin 登录。首次启动时，如果未设置 ADMIN_PASSWORD 环境变量，系统会生成一个随机密码并将其输出到服务日志中。

默认情况下，设置、用户和凭据绑定会持久保存在 ./data 中。

想使用自己的服务吗？首次启动前，创建 data/mcp_settings.json（参见配置）。启动后，可在控制面板中添加服务，也可以编辑现有文件并重启 MCPHub。

配置

首次启动前，创建 data/mcp_settings.json：

{
  "mcpServers": {
    "time": {
      "command": "npx",
      "args": ["-y", "time-mcp"]
    },
    "fetch": {
      "command": "uvx",
      "args": ["mcp-server-fetch"]
    }
  }
}

📖 如需查看包括 OAuth、环境变量等在内的完整选项，请参阅配置指南。

Docker 部署

复制并粘贴命令，请参阅使用 Docker 启动。请挂载 ./data，以便在重新创建容器后保留设置、用户和凭据绑定。

已发布两个位于 samanhappy/mcphub 下的镜像变体：

• latest ——默认镜像。包含 Node.js/pnpm、Python、uv/uvx、Git 和构建工具，可满足大多数 MCP 服务的需求。
• latest-full ——扩展镜像。增加了 Rust 工具链（Cargo/rustc）、Docker Engine 和 Playwright 浏览器（仅限 amd64，包含 Chrome + Firefox）。适用于基于 Rust 的服务或容器中运行容器的工作流。下载体积更大。

如需了解构建选项和 Docker-in-Docker 配置，请参阅 Docker 设置。

升级使用个人凭据的部署

数据库模式需要持久化的 MCPHUB_CREDENTIAL_ENCRYPTION_KEY 或现有密钥文件；系统不再自动生成本地密钥。替换正在运行的容器之前，请备份其原始密钥，并在部署密钥中保留相同的密钥值。如果密钥丢失，仅凭数据库备份无法恢复加密凭据。有关正在运行的部署以及升级失败后的恢复，请参阅凭据密钥升级与恢复指南。

访问控制面板

打开 http://localhost:3000（登录详情请参阅使用 Docker 启动）。你也可以预先设置密码：

# Docker: set admin password via environment variable
docker run -p 3000:3000 -v ./data:/app/data -e ADMIN_PASSWORD=your-secure-password samanhappy/mcphub

**提示：**为保障安全，请在首次登录后更改管理员密码。

**无头模式：**设置 DISABLE_WEB=true，即可跳过内置控制面板 UI 的服务，并仅运行 MCPHub 后端/API 和 MCP 端点。当你想直接通过 mcp_settings.json 管理服务时，此模式很有用。

连接 AI 客户端

通过以下方式连接 AI 客户端（Claude Desktop、Cursor 等）：

http://localhost:3000/mcp           # All servers
http://localhost:3000/mcp/{group}   # Specific group
http://localhost:3000/mcp/{server}  # Specific server
http://localhost:3000/mcp/$smart    # Smart routing
http://localhost:3000/mcp/$smart/{group}  # Smart routing within group

设置 SMART_ROUTING_PATH=my_smart，即可使用不带 $ 的 /mcp/my_smart（以及 /mcp/my_smart/{group}）。重启后生效；仍支持 /mcp/$smart。如果配置了 BASE_PATH，请将其加在 /mcp 之前。自定义路径段不能与现有服务名称、组名称或组 ID 相同。

安全提示：默认情况下，MCP 端点需要身份验证，以防意外暴露。如需允许未经身份验证访问 MCP，请在密钥部分禁用启用 Bearer 身份验证。跳过身份验证仅影响控制面板登录。请仅在可信环境中使用。

📖 有关端点的详细文档，请参阅 API 参考。

📚 文档

主题	说明
快速开始	5 分钟内快速上手
配置	MCP 服务配置选项
数据库模式	用于生产环境的 PostgreSQL 设置
OAuth	OAuth 2.0 客户端和服务端设置
智能路由	AI 驱动的工具发现
MCP Apps	交互式 Apps 透明代理
CLI 指南	在终端中管理和调用 hub
Docker 设置	Docker 部署指南

🧑‍💻 本地开发

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

本地开发使用 admin / admin123，并将可写的设置副本存储在 data/mcp_settings.dev.json，因此仓库中的 mcp_settings.json 不含凭据。

Windows 用户请分别启动后端和前端：pnpm backend:dev、pnpm frontend:dev

📖 有关详细的设置说明，请参阅开发指南。

🔍 技术栈

• 后端：Node.js、Express、TypeScript (ESM)
• 前端：React、Vite、Tailwind CSS
• 存储：默认使用基于文件的 mcp_settings.json；智能路由使用通过 TypeORM 配合 pgvector 的 PostgreSQL
• 身份验证：本地账户使用 JWT + bcrypt；持有者密钥；内置 OAuth 2.0 服务端（@node-oauth/oauth2-server）；可选的 Better Auth，用于 GitHub/Google 登录
• 协议：Model Context Protocol SDK

🏢 生产支持

在生产环境中运行 MCPHub？

直接与维护者合作，处理生产架构、OAuth/OIDC、 身份与访问控制、凭据管理、审计、Kubernetes 和高可用准备工作。

讨论生产试点 →

👥 贡献

欢迎贡献！如需讨论和支持，请访问我们的 Discord 社区。

❤️ 赞助

中国用户也可以通过微信支付支持我们，详见中文版。

致谢

• AtomGit：在中国托管 MCPHub，让中国大陆用户更便捷地访问本项目。

🌟 Star 历史

📄 许可证

本项目采用 Apache 2.0 许可证。