Skip to main content

​
概述

mcphub 二进制同时是 CLI 入口。不带参数调用 mcphub 启动服务器（保持原有行为）；带子命令则通过 HTTP API 操作本地或远端 hub。 
mcphub --help                    # 列出所有子命令
mcphub <command> [options]       # 执行子命令
mcphub                            # 旧行为：启动服务器（不变）
CLI 与服务器共用同一个 npm 包，无需额外安装。

​
登录

mcphub login --url http://localhost:3000 --username admin --password ********
JWT 会缓存到符合 XDG 规范的凭据文件中，权限 0600：
  • macOS/Linux: $XDG_DATA_HOME/mcphub/credentials.json（默认 ~/.local/share/mcphub/credentials.json）
  • 兼容旧路径：若 ~/.mcphub/credentials.json 已存在则继续使用
支持多 profile，可以在同一终端中并行操作 staging、prod 等： 
mcphub login --profile staging --url https://staging.hub.example
mcphub config use prod
mcphub config list
也可以完全绕过凭据文件：
覆盖方式来源
--url、--token、--bearer 参数单条命令
MCPHUB_URL、MCPHUB_TOKEN、MCPHUB_TOKEN_KIND 环境变量shell / CI
credentials.json 中的 active profile默认
解析顺序：命令行参数 → 环境变量 → active profile。

​
全局参数

参数用途
--url <url>覆盖 active profile 的 URL
--token <token>覆盖 active profile 的 token
--bearer将 --token 当作 bearer key 使用（默认是 JWT，走 x-auth-token）
--profile <name>选择非 current 的 profile
--json输出 JSON 而非人类可读表格
--debug出错时打印堆栈

​
子命令

​
servers

mcphub servers list
mcphub servers get <name>

# 从 JSON 文件添加：
mcphub servers add fetch --from-file ./fetch.json

# 或者内联（--arg / --env 可重复）：
mcphub servers add fetch \
  --type stdio --command uvx \
  --arg mcp-server-fetch \
  --env USER_AGENT=mcphub

mcphub servers remove fetch
mcphub servers toggle fetch --on
mcphub servers reload fetch

​
groups

mcphub groups list
mcphub groups add dev --description "开发工具组"
mcphub groups add-server dev fetch
mcphub groups remove-server dev fetch
mcphub groups remove dev
<group> 可填 UUID 或人类可读名称，CLI 会先列表再解析成 id。

​
keys

管理 bearer 密钥。管理员可管理系统级和用户级密钥；普通用户可管理自己的用户级密钥。 
mcphub keys list
mcphub keys create --name ci --access-type all
mcphub keys create --name dev-only --access-type groups --groups dev,staging
mcphub keys delete <id>
create 创建后服务端生成的 token 只会显示一次——记得当场复制。

​
tools —— 发现可调用的工具

tools 是 call 的发现索引：回答有哪些 tool、每个 tool 接受什么参数、归属哪个 server——不用手工解析 servers list 的嵌套 JSON。 
# 列出所有连接中 server 的全部 tool
mcphub tools list
mcphub tools list --json                       # 机器可读，默认不带 schema
mcphub tools list --schema --json              # 带上每个 tool 的 inputSchema
mcphub tools list --server fetch               # 限定到一个 server
mcphub tools list --enabled-only

# 查看单个 tool 的描述、参数表、完整 schema 与样例命令
mcphub tools get fetch_url
mcphub tools get fetch_url --server fetch      # 同名 tool 在多个 server 上时用 --server 消歧
mcphub tools schema fetch_url                  # `get` 的别名
tools get 的文本视图会先列参数表（带 required 标识），再打印完整 JSON schema，最后给一条可直接复制的 mcphub call ... 样例（必填参数已占位）。

​
call

调用 active profile 对应 hub 上的 MCP 工具。默认走 /mcp/$smart，由智能路由挑选工具。推荐的 agent 工作流：tools list → tools get → call。 
# 1. 找到一个 tool
mcphub tools list --json | jq '.[] | select(.name | contains("fetch"))'

# 2. 查 schema
mcphub tools get fetch_url --json | jq '.inputSchema'

# 3. 调用
mcphub call fetch_url url=https://example.com timeout=30
mcphub call fetch_url url=https://example.com --server fetch        # 指定到具体 server
mcphub call my_tool --group dev nested='{"a":1}'
mcphub call my_tool --params-json '{"deep":{"v":1}}'
call 的路由优先级：--smart > --server <name> > --group <name> > 默认（$smart）。三种最终都走 /mcp/<slug> 同一个端点；--server 是和 tools list/tools get 输出天然对齐的写法。 key=value 强转规则：
形式结果
n=42、f=1.5数字
b=true、b=false布尔
x=nullnull
obj={"a":1}、arr=[1,2]JSON 解析
payload=@./body.json从文件加载 JSON
phone=0123保留为字符串 "0123"（保护前导零）
其他字符串
--no-coerce 强制所有值按字符串处理。

​
export

下载 hub 当前的 mcp_settings.json。 
mcphub export --out backup.json
mcphub export > backup.json

​
discover / install（市场）

当 hub 开启了 systemConfig.discovery.enabled = true，CLI 即可浏览公共市场并把 server 装到自己的 hub 或客户端配置文件里。 
# 浏览 active profile 对应的 hub
mcphub discover --search github --limit 10
mcphub discover info amap-maps
mcphub discover categories
mcphub discover tags

# 装到 active hub（POST /api/servers）
mcphub install amap-maps --env AMAP_MAPS_API_KEY=...

# 从另一个 hub 装到 active hub
mcphub install some-server --remote https://hub.example.com --yes

# 仅打印片段（dry-run）
mcphub install amap-maps --dry-run

# 装到 Claude Desktop / OpenClaw 风格的客户端配置文件
mcphub install amap-maps --to file --out ~/Library/Application\ Support/Claude/claude_desktop_config.json
要点：
  • --type 选择安装方式（npm、docker、uvx、pip、binary）。不指定则由 hub 选第一个可用；指定但不存在时 CLI 会列出可用类型。
  • --env KEY=VAL（可重复）注入环境变量——预声明的键和新增的键都会合并进最终 env。
  • --to file 采用原子写（临时文件 + rename），中断不会破坏客户端配置。

​
退出码

退出码含义
0成功
1用法错误（参数缺失、未登录等）
2API 错误（hub 返回非 2xx）

​
Agent 自动化范式

所有命令都支持 --json，并读取 MCPHUB_URL / MCPHUB_TOKEN，因此 agent 可以纯 JSON 驱动整个”发现 → 调用”流程： 
export MCPHUB_URL=http://localhost:3000
export MCPHUB_TOKEN=$JWT

# 1. 枚举所有 tool
mcphub tools list --json > tools.json

# 2. 选定一个并读 schema
mcphub tools get fetch_url --json > schema.json

# 3. 根据 schema 构造参数并调用
mcphub call fetch_url --params-json "$(jq -n '{url:"https://example.com"}')" --json
tools list --json 的响应是扁平的（{server, serverStatus, name, description, enabled}），agent 一次过滤就能定位目标，不必再下钻 servers[*].tools[*]。

​
脚本与 CI

CLI 对 JSON 友好：所有命令都支持 --json；MCPHUB_URL / MCPHUB_TOKEN 在 CI 中可跳过凭据文件。 
export MCPHUB_URL=https://hub.example.com
export MCPHUB_TOKEN=$CI_HUB_TOKEN

mcphub servers list --json | jq '.[] | select(.status != "connected") | .name'
如果在 CI 中使用 bearer key，再追加 MCPHUB_TOKEN_KIND=bearer（或加 --bearer）。注意：只有 accessType=all 的系统级 bearer key 才能调用 /api/* 管理接口；受限 scope 的系统级密钥和用户级密钥仅用于 MCP transport。