mcp2cli

mcp2cli 用于把远端 MCP Server 暴露的工具，动态转换成本地命令行子命令。

它在启动时通过 tools/list 自动发现工具，并根据工具的 JSON Schema 生成参数与帮助信息。

功能特性

1. 通过 JSON 配置连接 MCP Streamable HTTP 服务端。
2. 启动时自动发现工具并生成二级命令（例如 weather cityInfo）。
3. 动态生成详细帮助，包括参数、输入 Schema、返回 Schema。
4. 根据工具输入 Schema 做本地参数校验（含必填、类型、枚举）。
5. 调用 MCP 工具并输出 JSON 结果。
6. 支持安装 wrapper 命令（软链接）并自动关联配置文件。
7. OAuth 2.1 PKCE 认证：自动发现、浏览器登录、Token 缓存与刷新。
8. 多 Server 统一管理：list 查看所有 Server 认证状态，login-all 批量登录。

安装

方式 1：源码构建

go build -o mcp2cli ./cmd/mcp2cli

或使用 Makefile：

make build
make test

方式 2：从 GitHub Release 安装

安装最新版：

curl -fsSL https://raw.githubusercontent.com/hengyunabc/mcp2cli/refs/heads/master/scripts/install-release.sh | bash

安装指定版本：

curl -fsSL https://raw.githubusercontent.com/hengyunabc/mcp2cli/refs/heads/master/scripts/install-release.sh | VERSION=v0.1.0 bash

安装脚本支持的环境变量：OWNER、REPO、BINARY、VERSION、INSTALL_DIR。

快速开始

方式 1：直接通过 --config 调用

示例配置见 examples/weather.json。

./mcp2cli --config examples/weather.json --help
./mcp2cli --config examples/weather.json tools
./mcp2cli --config examples/weather.json cityInfo --help
./mcp2cli --config examples/weather.json cityInfo --name hk

方式 2：安装 wrapper 命令（推荐）

Bearer Token 模式：

mcp2cli install weather --url https://example.com/mcp --token <token>

OAuth 模式（需要浏览器登录的 MCP Server）：

mcp2cli install code --url https://mcp.example.com/code/mcp --oauth

安装后会生成：

1. ~/.mcp2cli/bin/weather（指向 mcp2cli 的软链接）
2. ~/.mcp2cli/configs/weather.json

然后把 ~/.mcp2cli/bin 加入 PATH：

export PATH="$HOME/.mcp2cli/bin:$PATH"

之后可直接调用：

weather --help
weather tools
weather cityInfo --help
weather cityInfo --name hk

当以 weather 形式运行时，会自动读取 ~/.mcp2cli/configs/weather.json。

管理已安装命令

导入已有配置文件：

mcp2cli install weather --from-config /path/to/weather.json

查看已安装 wrapper 及认证状态：

mcp2cli list
# NAME      WRAPPER  AUTH           EXPIRES           URL
# code      yes      valid          2026-04-09 15:00  https://mcp.example.com/code/mcp
# coop      yes      expired        2026-04-08 06:30  https://mcp.example.com/coop/mcp
# weather   yes      bearer         -                 https://example.com/mcp

删除 wrapper（默认同时删除配置）：

mcp2cli remove weather

仅删除 wrapper，保留配置：

mcp2cli remove weather --keep-config

OAuth 认证

对于需要 OAuth 认证的 MCP Server，mcp2cli 支持完整的 OAuth 2.1 PKCE 流程。

认证流程

1. 自动发现 OAuth metadata（/.well-known/oauth-authorization-server）
2. 动态客户端注册（如 Server 支持）
3. PKCE S256 挑战
4. 打开浏览器完成授权
5. 本地 HTTP 回调接收 authorization code
6. 兑换 Token 并缓存到 ~/.mcp2cli/tokens/<name>.json
7. Token 过期时自动用 refresh_token 刷新，刷新失败则重新登录

单个登录

mcp2cli login code

批量登录所有 OAuth Server

mcp2cli login-all

自动认证

使用 OAuth 模式安装的命令，首次调用时会自动触发登录流程：

# 首次调用，自动弹浏览器登录
code search_code --search "CartHeadNotice"

# 后续调用，自动使用缓存 Token（过期则自动刷新）
code search_code --search "OrderService"

配置文件说明

完整示例：

Bearer Token 模式：

{
  "name": "weather",
  "server": {
    "url": "https://example.com/mcp",
    "transport": "streamable_http",
    "timeout_seconds": 30
  },
  "auth": {
    "type": "bearer",
    "token": "${WEATHER_MCP_TOKEN}"
  },
  "cli": {
    "description": "Weather MCP CLI",
    "include_return_schema_in_help": true,
    "pretty_json": false
  }
}

OAuth 模式：

{
  "name": "code",
  "server": {
    "url": "https://mcp.example.com/code/mcp",
    "transport": "streamable_http",
    "timeout_seconds": 30
  },
  "auth": {
    "type": "oauth"
  },
  "cli": {
    "description": "Code MCP CLI"
  }
}

字段说明：

1. server.url：MCP 服务地址（必填）。
2. server.transport：目前仅支持 streamable_http。
3. server.timeout_seconds：超时秒数，默认 30。
4. auth.type：可选，支持 bearer 和 oauth。
5. auth.token：当 auth.type=bearer 时必填；oauth 模式不需要。
6. cli.description：CLI 描述文本。
7. cli.include_return_schema_in_help：是否在帮助中显示返回 Schema，默认 true。
8. cli.pretty_json：是否美化 JSON 输出，默认 false。

配置文件支持环境变量展开（例如 "${WEATHER_MCP_TOKEN}"）。

常用命令

mcp2cli --help               # 帮助
mcp2cli version              # 版本
mcp2cli install --help       # 安装帮助
mcp2cli list                 # 列出所有 Server 及认证状态
mcp2cli login <name>         # 单个 OAuth 登录
mcp2cli login-all            # 批量 OAuth 登录
mcp2cli remove --help        # 删除帮助

如果已安装 wrapper（如 weather）：

weather --help
weather tools
weather <toolName> --help
weather <toolName> --arg value

环境变量

1. MCP2CLI_CONFIG：可指定默认配置文件路径（等价于 --config）。
2. MCP2CLI_HOME：自定义安装根目录（默认 ~/.mcp2cli）。

退出码

1. 0：成功
2. 1：通用错误
3. 2：参数校验错误
4. 3：连接或协议错误
5. 4：工具执行错误
6. 5：配置错误
7. 6：内部错误