Skip to main content
Glama
Sign In
deenesjakoruzh
RonieNeubauer

cli2mcp

by RonieNeubauer
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

cli2mcp

npm version npm downloads CI node license

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

通过解析命令行二进制文件的 --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>

cli2mcp demo

为什么

为现有的 CLI 编写 MCP 服务器是一项机械性工作：实例化 SDK、注册工具、手写输入模式、编组参数、生成子进程、格式化输出。每个二进制文件大约需要 80–150 行 TypeScript 代码，随着新工具的出现不断重复。

cli2mcp 只需一条命令即可完成。CLI 自身的 --help 是模式的真理来源 — 如果 rg 明天增加了一个标志，AI 明天就能看到它，无需更改代码。

Related MCP server: MCP-OpenAPI

安装

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 生成器

不适用

需要 OpenAPI 规范

不覆盖任意 CLI

将 bash / sh 封装为工具

~10

不适用 — 给 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）预期可以工作，但尚未被测试覆盖。请在 issues 中报告错误。

--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 代理调用您公开的 CLI，并使用代理选择的参数。您需要为您公开的 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 的输出提交 issue。

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

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

贡献

欢迎提交错误报告和补丁。新 CLI 的固定数据（test/fixtures/help/<cli>.txt + 形状测试）是最高效的贡献方式。

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

Star 历史

Star History Chart

如果 cli2mcp 为您节省了一个下午编写 MCP 样板代码的时间，点个 Star 可以帮助其他人找到它。

作者

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

许可证

MIT © 2026 Ronie Neubauer。

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP-OpenAPI

    rmasters
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that exposes HTTP methods defined in an OpenAPI specification as tools, enabling interaction with APIs via the Model Context Protocol.
    8
    MIT

  • mcp-cli-exec MCP Server

    jakenuts
    A
    license
    C
    quality
    D
    maintenance
    A CLI command execution server that enables running shell commands with structured output, providing detailed execution results including stdout, stderr, exit code, and execution duration.
    2
    38 npm
    12
    MIT

  • mcp-cli-catalog

    abcpro1
    A
    license
    Not graded
    quality
    D
    maintenance
    An MCP server that publishes CLI tools on your machine for discoverability by LLMs
    5 npm
    1
    MIT