mcp-to-cli 是一个基于 Bun 的 CLI 客户端,用于连接远程 MCP(Model Context Protocol)服务器,并在终端中直接与其工具(tools)、资源(resources)和提示词(prompts)交互。
【认证与 AI 代理注意事项】 当 CLI 触发 OAuth 流程时会自动打开浏览器。如果由 AI 代理使用该技能,连接时应始终传入 --no-open,使授权 URL 打印到终端而不是打开浏览器,再把打印出的 URL 转交给用户访问。CLI 在本地 http://localhost:8912/<connection>/callback 监听 OAuth 回调,用户在浏览器完成授权后会被自动捕获。
【安装与要求】 安装命令:bun install 要求:Bun 1.3+;一个可访问的 MCP 服务器 URL;使用 --ngrok 时环境变量中需要 NGROK_AUTHTOKEN。
【URL 快捷方式】 如果传入的是裸名称(不含 :// 或 .),CLI 会将其解析为 https://<name>.run.tools(Smithery)。例如 mcp-to-cli connect linear 等价于 mcp-to-cli connect https://linear.run.tools;notion、gmail 等同理。使用快捷方式时 CLI 会记录 Defaulting to Smithery URL: <resolved-url>。
【快速开始】 连接并保存:mcp-to-cli connect https://mcp.notion.com/mcp --name notion 不打开浏览器:mcp-to-cli connect https://mcp.notion.com/mcp --name notion --no-open 列出工具:mcp-to-cli notion tools list 交互调用工具:mcp-to-cli notion tools call search 带参数调用:mcp-to-cli notion tools call search --args '{"query": "meeting notes"}'
【连接管理】 connect <url> [--name <name>] [--ngrok] [--no-open] connections add / list(ls)/ remove(rm) 如果省略 --name,CLI 会从 URL 主机名提取名称(如 https://mcp.notion.com/mcp 变为 notion)。连接保存在 ~/.mcp-to-cli/profiles/<profile>/connections.json。
【Profiles】 可创建、列出、删除 profile;删除含子 profile 的需要 --recursive。可在任意命令使用 --profile <name> 或 -p <name>,也可设置环境变量 export MCP_CLI_PROFILE=<name>。Profile 可嵌套(如 acme/staging),子 profile 从父级继承连接与认证,查找链为 default → acme → acme/staging,写入始终只针对当前 profile。解析顺序:--profile 标志 > MCP_CLI_PROFILE 环境变量 > "default"。
【工具】 tools list [--offset N] [--limit N] [--full-description](默认每页 5 条,按字母排序) tools get <tool_name> 查看输入 schema tools call <tool_name> [--args '{...}'] [--json] 交互模式(默认):省略 --args 时按工具 JSON schema 逐个提示参数,必填项标有 *,可选字段按 Enter 跳过。 脚本模式:传入 --args '{"key": "value"}' 实现非交互。 JSON 输出:加 --json 获取原始 MCP 响应(便于管道/脚本);不加时输出截断在 80 行。
【资源与提示词】 resources list / resources get <uri>(resources read) prompts list / prompts get <prompt_name>(交互式提示参数)
【认证】 支持 OAuth 2.0 与 PKCE。服务器要求认证时,CLI 检测 UnauthorizedError 并启动 OAuth 流程;默认打开浏览器,传 --no-open 则打印 URL。本地共享回调服务器监听 http://localhost:8912/<connection>/callback,浏览器授权后 CLI 用 code 换取 token。Token 保存在 ~/.mcp-to-cli/profiles/<profile>/auth-<connection-name>.json 并自动复用。--no-open 偏好随连接保存并在后续请求自动使用。若浏览器未自动打开,CLI 会打印授权 URL,可复制到浏览器。
【ngrok 支持】 如果 MCP 服务器的 OAuth 提供方不允许 localhost 回调 URI,连接时使用 --ngrok: mcp-to-cli connect https://example.com/mcp --name example --ngrok 这会启动 ngrok 隧道,用公网 URL 暴露本地回调服务器。--ngrok 偏好随连接保存并自动复用。需要环境变量 NGROK_AUTHTOKEN 以及安装 @ngrok/ngrok 包。
【传输】 CLI 优先尝试 Streamable HTTP 传输,失败后回退到 SSE(Server-Sent Events),自动进行,无需配置。
【帮助】 每一级命令都支持 --help: mcp-to-cli --help mcp-to-cli <connection> --help mcp-to-cli <connection> tools --help mcp-to-cli <connection> tools call --help
【配置文件】 所有配置位于 ~/.mcp-to-cli/profiles/<profile>/:connections.json 保存服务器连接(名称、URL、时间戳);auth-<name>.json 保存每个连接的 OAuth token。Profile 是 ~/.mcp-to-cli/profiles/ 下的目录,默认 profile 为 default,子 profile(如 acme/staging)从父级继承。
【开发运行】 bun start(运行一次);bun dev(监听模式,变更自动重启)。
【示例工作流】 mcp-to-cli connect https://mcp.notion.com/mcp --name notion --no-open(打印授权 URL,在浏览器打开授权) mcp-to-cli notion tools list mcp-to-cli notion tools list --offset 5 mcp-to-cli notion tools get notion_search mcp-to-cli notion tools call notion_search --args '{"query": "Q1 planning"}' mcp-to-cli notion tools call notion_search --args '{"query": "Q1 planning"}' --json