McpHub

McpHub 位于你的 AI 编辑器与所有 MCP 服务之间。
你的 Agent 只需看到 3 个工具，而不是数百个，每次调用都会经过同一套安全防护，
而且你的服务只需在沙箱中运行一次，即可供 Cursor、Claude、Windsurf 和 VS Code 共享。

安装 · 连接编辑器 · 工作原理 · 代码模式 · 安全 · 控制面板 · 资源库 · Linux 与同步 · 配置 · 常见问题

✨ 一览

🚀 一行安装

curl -fsSL https://raw.githubusercontent.com/Soflutionltd/McpHub/main/get.sh | bash

脚本会为你的机器下载最新二进制文件（macOS 上为已签名的通用二进制文件，Linux 上为 x64 或 arm64），验证其 SHA-256 校验和，并将其安装到 ~/.local/bin/McpHub。然后：

McpHub dashboard  # Library tab: add servers from the official MCP Registry (or McpHub add)
McpHub generate   # index every tool once
McpHub install    # start the daemon at login (LaunchAgent on macOS, systemd --user on Linux)

git clone https://github.com/Soflutionltd/McpHub.git
cd McpHub
make install      # cargo build --release, install, sign

🔌 连接编辑器

守护进程监听 http://127.0.0.1:24680。你的令牌位于 ~/.McpHub/auth-token。

{
  "mcpServers": {
    "McpHub": {
      "url": "http://127.0.0.1:24680/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

claude mcp add --transport http mcphub http://127.0.0.1:24680/mcp \
  --header "Authorization: Bearer $(cat ~/.McpHub/auth-token)"

{
  "mcpServers": {
    "McpHub": { "command": "/Users/you/.local/bin/McpHub", "args": ["stdio"] }
  }
}

{
  "servers": {
    "mcphub": {
      "type": "http",
      "url": "http://127.0.0.1:24680/mcp",
      "headers": { "Authorization": "Bearer <your-token>" }
    }
  }
}

每个客户端使用一个配置文件。 为每个编辑器提供各自的视图：http://127.0.0.1:24680/mcp/cursor 仅显示 cursor 配置文件允许的内容（详见每个客户端的配置文件）。

项目感知型客户端（可选）

client/ 是一个小型 Node MCP 服务，位于编辑器和守护进程之间。它与正在运行的守护进程通信（通过 SSE，令牌来自 ~/.McpHub/auth-token），并在连接失败时回退到 McpHub stdio。它提供六个工具：

• mcphub_bootstrap：每次对话调用一次。从工作区解析项目，返回其别名和允许使用的服务，并提取精简的 MemoryPilot 上下文；对于没有项目条目的文件夹也同样适用。
• mcphub_search、mcphub_call：与守护进程功能相同，此外在工具或服务名称拼写错误时提供建议，并在参数出错时返回输入架构。
• mcphub_batch：一次往返中最多执行 20 个互不依赖的调用。
• mcphub_status、mcphub_savings：服务运行状况和如实的上下文大小对比。

每个项目的策略存储在 ~/.McpHub/projects.json 中（或 MCPHUB_PROJECTS 指定的路径），详见 client/projects.example.json。对于其中列出的工作区，只能访问其 allowedServers 中的服务；如果调用指向其他 Supabase 项目、App Store 应用或 Cloudflare 项目，则会被拒绝。没有此文件时，不会应用策略；如果文件无法读取，则会报错，不会静默忽略。

cd client && npm ci

{
  "mcpServers": {
    "McpHub": { "command": "node", "args": ["/path/to/McpHub/client/index.js"] }
  }
}

npm test 会使用临时项目文件，对本地守护进程运行冒烟测试（已配置 MemoryPilot 和 supabase）。

管理客户账户

连接到客户的 Stripe（或 Supabase、Cloudflare……）不应让你退出自己的账户，而你自己的 Agent 也绝不能误连到客户的服务。提供两个级别，从宽松到严格：

1. 客户拥有的服务（同一个 McpHub）。 使用客户自己的名称添加客户的服务（stripe-acme，并使用它自己的 OAuth 令牌或受限密钥，因为令牌按服务名称存储），并将其列入客户项目的 ownedServers：

"acme": {
  "workspaces": ["/Users/you/Clients/Acme"],
  "aliases": { "product": "Acme" },
  "allowedServers": ["MemoryPilot", "context7"],
  "ownedServers": ["stripe-acme"]
}

只有当 working_dir 位于客户工作区内时，客户拥有的服务才会响应，并显示在 mcphub_search 和 mcphub_status 中；仅提供 project 参数并不足够。一个服务由两个项目拥有会导致启动错误。这项防护在 Node 客户端中实现：直接连接到守护进程的编辑器仍能看到所有服务，因此请为它配置一个包含 "excludeServers": ["*-acme"] 的配置档。

2. 独立实例（完全隔离）。 对于有此要求的客户，运行第二个 McpHub，并为其使用独立的文件夹、端口、Keychain 服务、身份验证令牌和 LaunchAgent：

export MCPHUB_INSTANCE=acme MCPHUB_PORT=24690
McpHub add                 # writes ~/.McpHub-acme/config.json
McpHub oauth login stripe  # token stored under Keychain service McpHub-acme
McpHub install             # LaunchAgent com.soflution.mcphub.acme

命名实例不会导入编辑器中声明的服务，会拒绝使用主端口（24680），其令牌也会被主守护进程拒绝（反之亦然）。为该客户的工作区编辑器设置相同的变量，将其指向这个实例：

"McpHub": {
  "command": "node",
  "args": ["/path/to/McpHub/client/index.js"],
  "env": { "MCPHUB_INSTANCE": "acme", "MCPHUB_PORT": "24690" }
}

MCPHUB_HOME 和 MCPHUB_VAULT_SERVICE 可分别覆盖文件夹和 Keychain 服务。所有实例中的沙盒服务都无法访问任何 ~/.McpHub* 文件夹。macOS 和 Linux 支持命名实例自动启动。

🧭 工作原理

1. 编辑器只需连接一次 McpHub 守护进程（Streamable HTTP、SSE 或 stdio）。
2. Agent 可以使用三个工具：mcphub_search（搜索所有工具的 BM25 搜索）、mcphub_call（运行一个工具）和 mcphub_run（代码模式）。
3. 每次调用都会经过身份验证，按客户端配置档筛选，并依据工具固定项和权限进行检查，然后路由到相应服务；该服务会按需启动，空闲时停止。
4. 本地服务在 macOS 沙盒中运行，并使用最精简的环境；远程服务则通过 HTTP 直接访问，OAuth 令牌保存在 Keychain 中。
5. 每次调用都会写入审计日志。

节省令牌

将数十个 MCP 服务直接接入编辑器，会把每个工具的架构加载到每次对话中。在上述配置（35 个服务、928 个工具）下，这需要超过一百万个令牌，超出任何上下文窗口的容量。McpHub 用三个小型工具取而代之，并且只在 Agent 确实需要时才加载架构。

🧠 代码模式

对于多步骤或批量任务，Agent 使用 mcphub_run 发送一段简短的 JavaScript 程序：

const projects = await mcp.call("supabase", "list_projects", {});
const unhealthy = projects.filter(p => p.status !== "ACTIVE_HEALTHY");
return unhealthy.map(p => p.name);

• mcp.call(server, tool, args) 返回工具结果，mcp.search(query) 用于查找工具，console.log 的输出会被捕获。
• 程序在独立的 Node.js 进程中运行（版本 22.13 或更高），该进程通过 --permission 启动：无法访问文件、网络或子进程，并且运行在 macOS 沙盒中。
• 程序唯一的外部访问方式是 mcp.call，它会经过 McpHub 的所有防护（权限、隔离、配置档、审计）。
• 限制：settings.codeMode → { "timeoutSecs": 60, "maxCalls": 100 }，输出上限为 1 MB。

🛡️ 安全

MCP 服务是第三方程序，通常通过 npx -y package@latest 即时获取，并以你的权限运行。McpHub 会相应地对待它们。

McpHub vault set GITHUB_TOKEN      # masked prompt, stored in the Keychain
McpHub vault migrate               # move an existing secrets.env into the Keychain

McpHub pins status                  # what is quarantined and why
McpHub pins approve SERVER [TOOL]   # accept the new definition
McpHub pins scan                    # scan every cached tool, read-only

"settings": { "toolSecurity": { "pinning": "block", "scan": "block", "newTools": "block" } }

"settings": { "sandbox": "shield" }

McpHub sandbox                 # effective isolation of every server
McpHub sandbox show supabase   # the generated profile

"permissions": {
  "default": "allow",
  "rules": [
    { "server": "supabase", "tool": "delete_*", "action": "deny", "reason": "production" },
    { "server": "stripe", "tool": "*", "action": "confirm" }
  ]
}

🌐 远程服务与共享 OAuth

"sentry":  { "url": "https://mcp.sentry.dev/mcp" },
"aqara":   { "url": "https://agent.aqara.com/open/mcp", "headers": { "Authorization": "Bearer ${AQARA_API_KEY}" } }

远程服务通过 Streamable HTTP 直接连接，无需为每个服务单独运行 mcp-remote 进程。McpHub 实现了 MCP 授权规范：发现（RFC 9728 和 8414）、动态客户端注册、PKCE、资源指示器、自动刷新、仅限 HTTPS、令牌绑定到服务 URL 并存储在钥匙串中。

McpHub oauth status            # connection state of every remote server
McpHub oauth login sentry      # sign in through the browser, once
McpHub oauth logout sentry
McpHub oauth migrate --apply   # convert "npx mcp-remote URL" entries, keeping their tokens

📊 控制面板

运行 McpHub dashboard（将打开一个一次性链接，在浏览器中访问控制面板）。

服务：状态、工具，以及一键启用或停用	所有已编入索引的工具，均可搜索
每个服务的调用次数、错误数和延迟	添加、编辑、启用和停用服务 支持筛选的实时日志 一键重建工具缓存 实时令牌节省计数器 一键诊断故障服务

📚 库

控制面板中的 库 标签页是 McpHub 内置的官方 MCP Registry：搜索数千个服务，查看信任评分，然后点击 添加。

• 搜索在本地运行。 首次打开库时，McpHub 会在后台下载一次目录（首先是 GitHub MCP Registry 中的热门服务，只需几秒；随后下载完整的官方目录），并将其存入 ~/.McpHub/registry-cache/。之后，它只会获取有变更的内容，每天最多一次。搜索即时完成，也支持离线使用。
• 不会增加 Agent 的负担。 目录存放在控制面板和磁盘上。它不会向 Agent 的上下文添加任何工具定义，搜索之间也不会在内存中保留任何内容。
• 安装前查看信任评分（0 到 100 分），并了解每一分的详细依据：
  • 已验证的发布者：Registry 会检查命名空间（GitHub 账号或 DNS 域名），McpHub 会检查该发布者是否发布自己的代码；
  • 人气和活跃度：GitHub stars、最近更新时间、已归档的代码库；
  • 权限扫描：请求的密钥、纯 HTTP 端点、特权 Docker 选项、软件包完整性哈希、未固定的版本，以及服务可执行的操作（运行命令、访问文件、使用浏览器、付款等）。
• 一键添加各种类型的服务：远程服务（Streamable HTTP）、npm（npx）、Python（uvx）、Docker、.NET（dnx）和 .mcpb 软件包（下载后进行 SHA-256 校验，并解压到 ~/.McpHub 之外）。
• 密钥会存入 Keychain，绝不会存入 config.json。如果你已有所需密钥（如 GITHUB_TOKEN），就会直接复用。
• 远程服务通过 McpHub 的原生 OAuth 登录（点击一次 登录 即可），令牌存入 Keychain。
• 新服务继承所有防护措施：本地代码使用盾牌沙箱（Docker 保留其容器）、首次联系时固定工具并扫描说明、变更时隔离、审计日志、权限和配置文件。

在终端中运行：McpHub registry search postgres、McpHub registry info NAME、McpHub registry install NAME、McpHub registry sync。

Agent 会安装所需内容

这不会添加任何新工具（总计约 30 个令牌）。当 mcphub_search 找不到结果时，Agent 可以调用：

mcphub_call  server=mcphub  tool=registry_search   arguments={"query": "postgres"}
mcphub_call  server=mcphub  tool=registry_install  arguments={"name": "io.github.acme/postgres-mcp"}

服务会在应用相同防护措施的情况下安装，其工具会立即编入索引，调用也会记录在审计日志中。Agent 绝不会处理密钥：如果某个服务需要密钥，Agent 会请你前往控制面板完成设置。在 settings.registry 中进行控制：

"registry": { "agentInstall": "trusted", "minTrust": 60 }

agentInstall："trusted"（默认值，仅安装信任评分达到 minTrust 的服务）、"any" 或 "off"。

🐧 Linux 服务和同步

McpHub 在 Linux 服务上以相同方式运行，例如与运行在 VPS 上的 Agent 并行运行：

curl -fsSL https://raw.githubusercontent.com/Soflutionltd/McpHub/main/get.sh | bash
sudo apt install bubblewrap   # sandbox
McpHub install                # systemd --user service

• 使用 bubblewrap 进行沙箱隔离：采用与 macOS 相同的策略。每个机密文件夹（~/.ssh、~/.aws、~/.McpHub……）都会在内存中替换为空文件夹，每个机密文件都会替换为空文件；strict 模式会将整个系统设为只读，但临时文件夹、缓存和 allowWrite 除外。
• 机密信息存储在 ~/.McpHub/secrets.env 中，权限模式为 600，对沙箱隔离的服务不可见。McpHub vault set NAME 的用法相同。

在不同机器之间迁移设置，不留下任何明文机密信息：

McpHub sync export mcphub.sync.json --secrets   # on the Mac
McpHub sync import mcphub.sync.json --secrets   # on the server

导出内容是可移植的 config.json：每个机密信息都以 ${NAME} 引用表示（看起来像令牌的纯文本值会从副本中移除），主目录路径会转换为 ${HOME}/...。使用 --secrets 时，机密信息也会一并迁移，并使用口令加密（先用 scrypt，再用 ChaCha20-Poly1305）。没有口令时，文件只会显示机密信息名称。导入时，如果某个服务的程序在该机器上不存在，该服务会以禁用状态导入；解密后的机密信息会存入 Keychain（macOS）或 secrets.env（Linux）。对于脚本，请设置 MCPHUB_SYNC_PASSPHRASE。

⚙️ 配置

所有内容都存储在 ~/.McpHub/config.json 中，并会在守护进程运行时热重载。

{
  "servers": {
    "supabase": {
      "command": "npx",
      "args": ["-y", "@supabase/mcp-server-supabase"],
      "env": { "SUPABASE_ACCESS_TOKEN": "${SUPABASE_ACCESS_TOKEN}" },
      "tools": { "exclude": ["delete_*", "pause_project"] },
      "toolDescriptions": { "list_projects": "List my Supabase projects" }
    },
    "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "readOnly": true },
    "sentry": { "url": "https://mcp.sentry.dev/mcp" }
  },
  "settings": {
    "mode": "discover",
    "sandbox": "shield",
    "toolSecurity": { "pinning": "block", "scan": "block", "newTools": "block" },
    "permissions": { "default": "allow", "rules": [] },
    "profiles": {
      "cursor": { "servers": ["supabase", "git*"], "excludeTools": ["supabase/execute_sql"] },
      "review": { "readOnly": true }
    },
    "codeMode": { "timeoutSecs": 60, "maxCalls": 100 },
    "idleTimeout": 300
  }
}

每个服务的选项

每个客户端的配置文件

配置文件决定每个客户端可以查看和调用哪些内容：servers 和 excludeServers（glob）、excludeTools（"server/tool" glob）以及 readOnly。通过 http://127.0.0.1:24680/mcp/<profile>、/sse?profile=<profile>，或在 stdio 模式下使用 MCPHUB_PROFILE=<profile> 选择配置文件。

模式

• discover（默认）：Agent 可以看到 mcphub_search、mcphub_call 和 mcphub_run。
• passthrough：直接将每个工具公开为 server__tool（完全可见，但令牌成本更高）。

🧰 CLI

McpHub serve              # HTTP daemon (Streamable HTTP /mcp, SSE /sse, dashboard)
McpHub stdio              # stdio mode for editors that spawn the process
McpHub install            # start at login · McpHub uninstall
McpHub generate           # start every server and index its tools
McpHub status | doctor    # configuration, cache and health diagnostics
McpHub search "send email"
McpHub dashboard          # open the dashboard (one-time link)
McpHub logs               # follow the daemon log
McpHub add                # interactive server wizard
McpHub vault ...          # Keychain secrets: status, list, set, get, rm, migrate
McpHub registry ...       # Library: search, info, install, uninstall, sync
McpHub sync ...           # export / import to another machine, secrets encrypted
McpHub oauth ...          # remote servers: status, login, logout, migrate
McpHub pins ...           # tool pinning: status, approve, reset, scan
McpHub sandbox [show S]   # server isolation
McpHub policy test S T    # which permission applies
McpHub audit --tail 50    # recent calls
McpHub update | version | help

文件：~/.McpHub/（配置、缓存、固定项、审计日志、令牌；用于命名实例的 ~/.McpHub-<name>/）以及 ~/Library/Logs/McpHub/<server>.stderr.log（各服务的错误输出）。

❓ 常见问题

McpHub uninstall
rm ~/.local/bin/McpHub
rm -rf ~/.McpHub

_{MIT 许可证 · 由 SOFLUTION LTD 制作}