MCP Hub

MCP Hub 是一个用于管理 MCP 服务器和客户端的中央协调器，提供两个关键接口：

1. 管理接口 (/api/*): 通过统一的 REST API 和 Web UI 管理多个 MCP 服务器
2. MCP 服务器接口 (/mcp): 通过单一端点连接任意 MCP 客户端以访问所有服务器功能

这种双接口方法意味着您可以通过 Hub 的 UI 来管理服务器，而 MCP 客户端（如 Claude Desktop、Cline 等）只需连接到一个端点 (localhost:37373/mcp) 即可访问所有功能。实现了 MCP 2025-03-26 规范。

功能支持

类别	功能	支持	备注
传输
	streamable-http	✅	远程服务器的主要传输协议
	SSE	✅	远程服务器的备用传输协议
	STDIO	✅	用于运行本地服务器
认证
	OAuth 2.0	✅	包含 PKCE 流程
	Headers	✅	用于 API 密钥/令牌
能力
	工具	✅	列出工具
	🔔 工具列表更改	✅	实时更新
	资源	✅	完整支持
	🔔 资源列表更改	✅	实时更新
	资源模板	✅	URI 模板
	提示	✅	完整支持
	🔔 提示列表更改	✅	实时更新
	根目录	❌	不支持
	抽样	❌	不支持
	完成	❌	不支持
市场
	服务器发现	✅	浏览可用服务器
	安装	✅	自动配置
实时
	状态更新	✅	服务器及连接状态
	能力更新	✅	自动刷新
	事件流至客户端	✅	基于 SSE
	自动重连	✅	包含退避策略
开发
	热重载	✅	在文件更改时自动重启 MCP 服务器（使用 dev 模式）
配置
	${} 语法	✅	在所有字段中支持环境变量和命令执行
	VS Code 兼容性	✅	支持 servers 键、${env:}、${input:}、预定义变量
	JSON5 支持	✅	配置文件中的注释和尾随逗号

简化的客户端配置

通过一个端点配置所有 MCP 客户端：

{
    "mcpServers" : {
        "Hub": {
            "url" : "http://localhost:37373/mcp"  
        }
    }
}

Hub 自动：

• 对能力进行命名空间划分以防止冲突（例如，filesystem__search vs database__search）
• 将请求路由到适当的服务器
• 当服务器添加或移除时实时更新能力
• 处理认证和连接管理

关键特性

• 统一的 MCP 服务器端点 (/mcp):

  • 所有 MCP 客户端连接的单一端点
  • 通过一个连接访问所有托管服务器的能力
  • 自动命名空间划分防止服务器之间的冲突
  • 当服务器变化时实时更新能力
  • 简化客户端配置 - 只需一个端点而不是多个

• 动态服务器管理:

  • 按需启动、停止、启用/禁用服务器
  • 实时配置更新并自动重新连接服务器
  • 支持本地（STDIO）和远程（streamable-http/SSE）MCP 服务器
  • 健康监控和自动恢复
  • 带有 PKCE 流程的 OAuth 认证
  • 基于头的令牌认证

• 统一的 REST API:

  • 从任何连接的服务器执行工具
  • 访问资源和资源模板
  • 通过服务发送事件（SSE）实时状态更新
  • 服务器管理的完整 CRUD 操作

• 实时事件与监控:

  • 实时服务器状态和能力更新
  • 客户端连接跟踪
  • 工具和资源列表更改通知
  • 结构化 JSON 日志，带有文件输出

• 客户端连接管理:

  • 通过 /api/events 简单的 SSE 客户端连接
  • 断开连接时自动清理连接
  • 无客户端连接时可选自动关闭
  • 实时连接状态监控

• 进程生命周期管理:

  • 平稳的启动和关闭处理
  • 正确清理服务器连接
  • 错误恢复和重新连接

• 工作区管理:

  • 跨不同工作目录跟踪活动的 MCP Hub 实例
  • 在符合 XDG 规范的状态目录中全局工作区缓存
  • 通过 SSE 事件实时更新工作区
  • 列出和监控活动工作区的 API 端点

组件

Hub 服务器

主要管理服务器，它：

• 维护与多个 MCP 服务器的连接
• 提供统一的 API 访问服务器能力
• 处理服务器生命周期和健康监控
• 管理 SSE 客户端连接和事件
• 处理配置更新和服务器重新连接

MCP 服务器

连接的服务，它们：

• 提供工具、资源、模板和提示
• 支持两种连接模式：
  • 用于本地操作的脚本 STDIO 服务器
  • 带有 OAuth 支持的远程服务器（streamable-http/SSE）
• 实现实时能力更新
• 支持自动状态恢复
• 在各种传输类型之间保持一致的接口

安装

npm install -g mcp-hub

基本用法

启动 Hub 服务器：

mcp-hub --port 3000 --config path/to/config.json

# 或者使用多个配置文件（按顺序合并）
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json

CLI 选项

选项:
  --port            服务器运行的端口（必需）
  --config          配置文件路径。可以多次指定。按顺序合并。（必需）
  --watch           监视配置文件的变化，仅更新受影响的服务器（默认：false）
  --auto-shutdown   是否在没有客户端连接时自动关闭（默认：false）
  --shutdown-delay  启用自动关闭时延迟关闭的毫秒数（默认：0）
  -h, --help       显示帮助信息

配置

MCP Hub 使用 JSON 配置文件来定义托管服务器，并使用 通用 ${} 占位符语法 来支持环境变量和命令执行。

VS Code 配置兼容性

MCP Hub 提供无缝兼容 VS Code 的 .vscode/mcp.json 配置格式，允许您在 VS Code 和 MCP Hub 中使用相同的配置文件。

支持的功能

服务器配置键

同时支持 mcpServers 和 servers 键：

{
  "servers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "perplexity": {
      "command": "npx", 
      "args": ["-y", "server-perplexity-ask"],
      "env": {
        "API_KEY": "${env:PERPLEXITY_API_KEY}"
      }
    }
  }
}

变量替换

MCP Hub 支持 VS Code 样式的变量替换：

• 环境变量：${env:VARIABLE_NAME} 或 ${VARIABLE_NAME}
• 工作区变量：${workspaceFolder}、${userHome}、${pathSeparator}
• 命令执行：${cmd: command args}

支持的预定义变量：

• ${workspaceFolder} - mcp-hub 运行的目录
• ${userHome} - 用户的主目录
• ${pathSeparator} - 操作系统路径分隔符（/ 或 \）
• ${workspaceFolderBasename} - 仅文件夹名称
• ${cwd} - workspaceFolder 的别名
• ${/} - VS Code 缩写形式的路径分隔符

VS Code 输入变量

对于 VS Code 配置中的 ${input:} 变量，使用 MCP_HUB_ENV 环境变量：

# 全局设置输入变量
export MCP_HUB_ENV='{"input:api-key":"your-secret-key","input:database-url":"postgresql://..."}'

# 然后在配置中使用
{
  "servers": {
    "myserver": {
      "env": {
        "API_KEY": "${input:api-key}"
      }
    }
  }
}

从 VS Code 迁移

现有的 .vscode/mcp.json 文件可以直接与 MCP Hub 一起使用。只需指向 MCP Hub 的 VS Code 配置：

mcp-hub --config .vscode/mcp.json --port 3000

多个配置文件

MCP Hub 支持加载多个配置文件，这些文件按顺序合并。这使得配置管理更加灵活：

• 全局配置：系统范围的设置（例如，~/.config/mcphub/global.json）
• 项目配置：项目特定的设置（例如，./.mcphub/project.json）
• 环境配置：环境特定的覆盖

当指定了多个配置文件时，它们按顺序合并，后面的文件会覆盖前面的文件：

# 先加载全局配置，然后项目配置覆盖
mcp-hub --port 3000 --config ~/.config/mcphub/global.json --config ./.mcphub/project.json

合并行为：

• mcpServers 部分合并（后面文件中的服务器定义覆盖前面的）
• 其他顶级属性完全被后面的文件替换
• 缺失的配置文件会被静默跳过

通用占位符语法

• ${ENV_VAR} 或 ${env:ENV_VAR} - 解析环境变量
• ${cmd: command args} - 执行命令并使用输出
• ${workspaceFolder} - mcp-hub 运行的目录
• ${userHome} - 用户的主目录
• ${pathSeparator} - 操作系统路径分隔符
• ${input:variable-id} - 从 MCP_HUB_ENV 解析（VS Code 兼容）
• null 或 "" - 回退到 process.env

配置示例

本地 STDIO 服务器

{
  "mcpServers": {
    "local-server": {
      "command": "${MCP_BINARY_PATH}/server",
      "args": [
        "--token", "${API_TOKEN}",
        "--database", "${DB_URL}",
        "--secret", "${cmd: op read op://vault/secret}"
      ],
      "env": {
        "API_TOKEN": "${cmd: aws ssm get-parameter --name /app/token --query Parameter.Value --output text}",
        "DB_URL": "postgresql://user:${DB_PASSWORD}@localhost/myapp",
        "DB_PASSWORD": "${cmd: op read op://vault/db/password}",
        "FALLBACK_VAR": null
      },
      "dev": {
        "enabled": true,
        "watch": ["src/**/*.js", "**/*.json"],
        "cwd": "/absolute/path/to/server/directory"
      }
    }
  }
}

远程服务器

{
  "mcpServers": {
    "remote-server": {
      "url": "https://${PRIVATE_DOMAIN}/mcp",
      "headers": {
        "Authorization": "Bearer ${cmd: op read op://vault/api/token}",
        "X-Custom-Header": "${CUSTOM_VALUE}"
      }
    }
  }
}

配置选项

MCP Hub 支持 STDIO 服务器和远程服务器（streamable-http/SSE）。服务器类型会根据配置自动检测。所有字段都支持通用 ${} 占位符语法。

STDIO 服务器选项

用于本地运行基于脚本的 MCP 服务器：

• command: 启动 MCP 服务器可执行文件的命令（支持 ${VARIABLE} 和 ${cmd: command}）
• args: 命令行参数数组（支持 ${VARIABLE} 和 ${cmd: command} 占位符）
• env: 环境变量，具有占位符解析和系统回退
• cwd: 进程生成 MCP 服务器的工作目录
• dev: 开发模式配置（可选）
  • enabled: 启用/禁用开发模式（默认：true）
  • watch: 要监视更改的通配符模式数组（默认：["/*.js", "/.ts", "**/.json"]）
  • cwd: 必需 服务器工作目录的绝对路径，用于文件监视

全局环境变量 (MCP_HUB_ENV)

MCP Hub 会在其自身的进程环境中查找环境变量 MCP_HUB_ENV（JSON 字符串）。如果设置了该变量，其中的所有键值对都会注入到每个托管 MCP 服务器的环境中（包括 stdio 和远程）。这对于传递密钥、令牌或其他共享配置到所有服务器而不必在每个服务器配置中重复它们非常有用。

• 服务器特定的 env 字段始终覆盖来自 MCP_HUB_ENV 的值。
• 示例用法：

  MCP_HUB_ENV='{"DBUS_SESSION_BUS_ADDRESS":"/run/user/1000/bus","MY_TOKEN":"abc"}' mcp-hub --port 3000 --config path/to/config.json
  

远程服务器选项

用于连接到远程 MCP 服务器：

• url: 服务器端点 URL（支持 ${VARIABLE} 和 ${cmd: command} 占位符）
• headers: 认证头（支持 ${VARIABLE} 和 ${cmd: command} 占位符）

服务器类型检测

服务器类型由以下决定：

• STDIO 服务器 → 具有 command 字段
• 远程服务器 → 具有 url 字段

注意：服务器配置不能混用 STDIO 和远程服务器字段。

占位符解析顺序

1. 命令优先：${cmd: command args} 首先执行
2. 环境变量：${VAR} 从 env 对象解析，然后从 process.env
3. 回退：null 或 "" 值回退到 process.env
4. 多遍：变量之间的依赖关系会自动解析

Nix

Nixpkgs 安装

即将推出...

Flake 安装

只需将其添加到您的 NixOS flake.nix 或 home-manager：

inputs = {
  mcp-hub.url = "github:ravitemer/mcp-hub";
  ...
}

要将 mcp-hub 整合到您的 NixOS/Home Manager 配置中，请分别在您的环境 systemPackages 或 home.packages 中添加以下内容：

inputs.mcp-hub.packages."${system}".default

无需安装使用

如果您想使用 mcphub.nvim 而不将 mcp-hub 服务器添加到 PATH 中，可以在插件配置中的 cmd 命令中添加 mcp-hub 的 Nix 存储路径：

Nixvim 示例：

{ mcphub-nvim, mcp-hub, ... }:
{
  extraPlugins = [mcphub-nvim];
  extraConfigLua = ''
    require("mcphub").setup({
        port = 3000,
        config = vim.fn.expand("~/mcp-hub/mcp-servers.json"),
        cmd = "${mcp-hub}/bin/mcp-hub"
    })
  '';
}

# 其中
{
  # 对于 nixpkgs（尚未提供）
  mcp-hub = pkgs.mcp-hub;

  # 对于 flakes
  mcp-hub = inputs.mcp-hub.packages."${system}".default;
}

示例集成

Neovim 集成

ravitemer/mcphub.nvim 插件提供了与 Neovim 的无缝集成，允许直接从编辑器与 MCP Hub 交互：

• 直接从 Neovim 执行 MCP 工具
• 在编辑工作流程中访问 MCP 资源
• Neovim 中的实时状态更新
• 自动安装带有市场添加的 MCP 服务器

REST API

健康和状态

健康检查

GET /api/health

健康端点提供全面的状态信息，包括：

• 当前 hub 状态（启动中、就绪、重新启动中、已重新启动、停止中、已停止、错误）
• 已连接服务器的状态和能力
• 活跃的 SSE 连接详情
• 详细的连接