cli2mcp

cli2mcp

状态： v0.1——早期版本。仅支持 Stdio 传输。1.0 之前 API 可能会变更。

只需解析命令行二进制文件的 --help 输出，并在启动时生成 JSON Schema，即可将其作为 Model Context Protocol 工具公开。只需一条命令，无需编写样板代码。

兼容任何 MCP 客户端——Claude Desktop、ChatGPT（通过 OpenAI Agents SDK）、Cursor、Gemini CLI、Cline、Windsurf、Continue、Zed，以及任何支持 MCP Stdio 传输的客户端。

npx cli2mcp <command>

---

为什么选择它

为已有的 CLI 编写 MCP 服务是一项机械性工作：实例化 SDK、注册工具、手写输入 Schema、整理参数、启动子进程、格式化输出。每个二进制文件大约需要 80–150 行 TypeScript，而且每次有新工具推出都要重复这些工作。

cli2mcp 一条命令即可完成。CLI 自身的 --help 是 Schema 的真实依据——如果 rg 明天添加了一个标志，AI 明天就能看到，无需更改代码。

---

安装

npm install -g cli2mcp
# or invoke without installing
npx cli2mcp <command>

需要 Node.js 22+。

---

配置 MCP 客户端

客户端会将 cli2mcp 作为 Stdio 子进程启动。为要公开的每个 CLI 添加一条配置。

Claude Desktop

配置文件位置：

操作系统	路径
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json
Linux	~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ripgrep": {
      "command": "npx",
      "args": ["-y", "cli2mcp", "rg", "--name", "ripgrep"]
    },
    "jq": {
      "command": "npx",
      "args": ["-y", "cli2mcp", "jq"]
    }
  }
}

编辑后重启 Claude Desktop。

其他客户端

客户端	配置文件	格式
ChatGPT（OpenAI Agents SDK）	MCPServerStdio 参数——参阅 OpenAI Agents 文档	command: "npx"、args: ["-y", "cli2mcp", "<cli>"]
Cursor	.cursor/mcp.json（项目）或 ~/.cursor/mcp.json（全局）	与上文相同的 mcpServers 块
Cline	VS Code → Cline → MCP Settings → cline_mcp_settings.json	相同的 mcpServers 块
Windsurf	~/.codeium/windsurf/mcp_config.json	相同的 mcpServers 块
Gemini CLI	~/.gemini/settings.json	相同的 mcpServers 块
Continue	~/.continue/config.json → experimental.modelContextProtocolServers	相同的启动配置
Zed	~/.config/zed/settings.json → context_servers	相同的启动配置
任何支持 Stdio 的 MCP 客户端	参阅客户端文档	相同的启动配置：npx -y cli2mcp <command>

请参阅各客户端的文档，了解适用于你平台的准确配置路径——这些路径会不断变化，不保证与上表一致。

---

快速上手——复制粘贴配置

将以下任一配置添加到客户端的 mcpServers 块中（各客户端的路径见上文）。每项配置都会将一个常用 CLI 封装为 AI 可直接调用的 MCP 工具。

{
  "mcpServers": {
    "ripgrep": {
      "command": "npx",
      "args": ["-y", "cli2mcp", "rg", "--name", "ripgrep",
               "--description", "Recursively search files with regex"]
    },
    "jq": {
      "command": "npx",
      "args": ["-y", "cli2mcp", "jq",
               "--description", "Query and transform JSON via stdin"]
    },
    "pandoc": {
      "command": "npx",
      "args": ["-y", "cli2mcp", "pandoc",
               "--description", "Convert documents between markup formats"]
    },
    "sqlite3": {
      "command": "npx",
      "args": ["-y", "cli2mcp", "sqlite3",
               "--description", "Run SQL against a SQLite database file",
               "--cwd", "/path/to/safe/dir"]
    },
    "yt-dlp": {
      "command": "npx",
      "args": ["-y", "cli2mcp", "yt-dlp",
               "--description", "Download media from URLs",
               "--cwd", "/path/to/downloads",
               "--timeout", "300000"]
    }
  }
}

每个 CLI 都必须已安装并位于 PATH 中。cli2mcp 不会为你安装它们。

---

对比

方式	每个 CLI 的代码行数	新增标志的处理	维护
手写 MCP 服务（TypeScript SDK）	~80–150	手动编辑架构	随 CLI 的发布周期
OpenAPI → MCP 生成器	n/a	需要 OpenAPI 规范	不支持任意 CLI
将 bash / sh 封装为工具	~10	n/a — 为 AI 提供 shell	不安全、没有架构、没有沙箱
cli2mcp <command>	0	下次启动时自动处理	无需维护 — 重新读取 --help

最接近的方案是 FastMCP 的 from_openapi，但它不支持任意 CLI 二进制文件。截至 2026 年 4 月，还没有其他已发布的工具能通过一条命令将任意 --help 输出转换为类型化的 MCP 工具。

---

已验证的目标

这些 CLI 已纳入测试套件，或已通过端到端手动测试：

CLI	状态	备注
jq	✅ 已测试	正确捕获输出到 stderr 的帮助信息；stdin 管道正常
ripgrep（rg）	✅ 已测试	推断出 90 多个标志；支持位置参数 args
curl	✅ 固件测试	已根据随附的固件验证结构提取
node	✅ 集成测试	端到端 MCP 握手和 tools/call

其他 POSIX 风格的 CLI（例如 ffmpeg、yt-dlp、pandoc、sqlite3、imagemagick）预计也能正常工作，但目前尚未纳入测试。请在问题中报告错误。

---

--help 如何转换为 JSON Schema

帮助片段	MCP 属性
--flag	boolean
--flag <value> / <file> / <path>	string
--flag <n> / <ms> / <size>	number
--flag <a|b|c>	含可选值的 string 枚举
可重复标志	array<string>
位置参数	args: array<string>
保留输入 stdin	通过管道传递给子进程 stdin 的 string

如果遇到非标准的 --help，导致解析失败，cli2mcp 会回退为单个可变参数位置参数 args，让工具仍可使用 — 模型得到的是自由格式的参数列表，而不是类型化标志。

---

选项

cli2mcp <command> [options]

  --name <name>         Tool name shown to the AI           (default: <command>)
  --description <text>  Tool description shown to the AI    (default: first --help line)
  --timeout <ms>        Subprocess timeout per call         (default: 60000)
  --cwd <path>          Working directory for subprocess    (default: process.cwd())
  --env <KEY=VALUE>     Extra environment variables         (repeatable)
  --stderr <mode>       stderr handling:
                          include  →  appended to tool output (default)
                          drop     →  discarded
                          error    →  any stderr → isError: true
  -h, --help            Show help

管道传递 stdin

保留输入属性 stdin 会通过管道传递给子进程：

{ "args": [".name"], "stdin": "{\"name\": \"cli2mcp\"}" }

---

工作原理

cli2mcp rg
   │
   ├─ 1. spawn: rg --help          →  capture stdout + stderr
   ├─ 2. parse help text           →  CliShape { flags, positionals, description }
   ├─ 3. synthesize JSON Schema    →  inputSchema
   ├─ 4. register one MCP tool     →  name: "rg", schema: <above>
   └─ 5. start stdio MCP server    →  await client connection

On tools/call:
   { args, flags, stdin? }  →  argv builder  →  execa(rg, argv, { stdin })
                                                           │
                                          stdout (+ stderr) → content[text]

非零退出 → { isError: true, content: [{ type: "text", text: <stderr> }] }（除非使用 --stderr drop）。

---

安全性

cli2mcp 允许 AI Agent 使用你公开的 CLI，并传入 Agent 选择的参数。你需要对这些 CLI 在你的机器上能执行的操作负责。

实用建议：

• 只公开你能接受其影响范围的 CLI。 jq、rg、pandoc 大多是安全的（只读、行为确定）。curl、ffmpeg --output、sqlite3、rm、kubectl、aws 则不安全。
• AI 不在沙箱中运行。 提示词注入攻击可能导致公开的 curl 获取 evil.example.com 的内容，或导致公开的 rm 删除文件，等等。
• 封装会访问文件的 CLI 时，使用 --cwd 限制文件系统范围。
• 谨慎使用 --env。 不要传递模型不应访问的凭据。
• 切勿公开 sh、bash、zsh、python -c 或任何具有 eval 语义的程序 — 这会绕过 cli2mcp 提供的所有防护。

基于帮助信息生成架构的设计可以降低 argv 格式错误的风险，但不能消除滥用风险。应将每个公开的 CLI 视为委派出去的能力，而不是沙箱。

---

故障排查

CLI 没有 --help 标志。 cli2mcp 仍会通过一个 args 位置参数启动。AI 可以自由传递参数；但你将无法获得类型化标志推断。

生成的架构为空或有误。 手动运行 cli2mcp <command> 并检查 tools/list 响应（使用 npx @modelcontextprotocol/inspector）。最常见的原因是帮助信息的格式不标准（没有 --long-form 标志、列未对齐）。请提交问题，并附上 <command> --help 的输出。

子进程挂起。 默认的 60s 超时会将其终止。通过 --timeout 调高超时时间。如果你的 CLI 是交互式的（会等待 TTY），cli2mcp 无法提供帮助——请改用 stdin 管道传入输入。

标志未传递。 设置 --stderr include（默认值），并检查 content[].text。如果标志没有出现在 argv 中，说明帮助信息解析器未能提取该标志——请提交问题。

---

贡献

欢迎提交 Bug 报告和补丁。为新的 CLI 添加测试样例（test/fixtures/help/<cli>.txt + 一个形状测试）是最有价值的贡献。

pnpm install
pnpm test         # vitest
pnpm typecheck    # tsc --noEmit
pnpm lint         # biome check

---

Star 历史

如果 cli2mcp 为你省去了一个下午编写 MCP 样板代码的时间，点个 Star 可以帮助更多人发现它。

---

作者

由 Ronie Neubauer 构建——首席工程师，拥有 22+ 年生产系统交付经验。

• GitHub： @RonieNeubauer
• 博客：ronieneubauer.com
• 问题与想法：github.com/RonieNeubauer/cli2mcp/discussions

---

许可证

MIT © 2026 Ronie Neubauer。