cli2mcp MCP server
✓ VerifiedExpose any command-line binary as a Model Context Protocol tool by automatically synthesizing JSON schemas from its help output.
Also known as RonieNeubauer/cli2mcp
- Stars
- 13
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 0.1.4
- Last commit
- Apr 29, 2026
- License
- MIT
What is cli2mcp MCP?
cli2mcp exposes any command-line binary as a Model Context Protocol tool by automatically synthesizing JSON schemas from its help output.
Summary generated from the project's README
About cli2mcp MCP server
cli2mcp allows developers to turn any command-line binary into a Model Context Protocol tool without writing manual TypeScript boilerplate. It works by executing the command with a help flag and automatically generating a JSON Schema based on the output. This process enables AI clients to understand and use command-line arguments, flags, and positional parameters immediately.
The server operates via stdio transport, making it compatible with a wide range of MCP-supported clients including Claude Desktop, Cursor, Windsurf, and the OpenAI Agents SDK. Users can configure specific settings such as the working directory using the --cwd option, set custom timeouts, or pass environment variables via --env. Because it relies on the existing help text of the target binary, the tool definitions stay up to date whenever the underlying CLI is updated.
To use it, you simply run the command through npx or install it globally. It is designed for developers who want to extend their AI agents with existing system tools like jq, ripgrep, or pandoc without the mechanical work of manual schema definition.
Written from the project's README. Every use case is checked against a quote from it.
How to install cli2mcp MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall cli2mcp MCP in Claude Code
$ claude mcp add cli2mcp -- npx -y cli2mcpInstall cli2mcp MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"cli2mcp": {
"command": "npx",
"args": [
"-y",
"cli2mcp"
]
}
}
}Install cli2mcp MCP in VS Code
.vscode/mcp.json
{
"servers": {
"cli2mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"cli2mcp"
]
}
}
}Install cli2mcp MCP in VS Code CLI
$ code --add-mcp '{"name":"cli2mcp","type":"stdio","command":"npx","args":["-y","cli2mcp"]}'Install cli2mcp MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"cli2mcp": {
"command": "npx",
"args": [
"-y",
"cli2mcp"
]
}
}
}Install cli2mcp MCP in Codex
$ codex mcp add cli2mcp -- npx -y cli2mcpInstall cli2mcp MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.cli2mcp] command = "npx" args = ["-y", "cli2mcp"]
Install cli2mcp MCP in Gemini CLI
$ gemini mcp add -s user cli2mcp npx -- -y cli2mcpInstall cli2mcp MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"cli2mcp": {
"command": "npx",
"args": [
"-y",
"cli2mcp"
]
}
}
}Automated checks
Ran Nov 15, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableronieneubauer/cli2mcp is public and reachablegithub.com/ronieneubauer/cli2mcp ↗Pass
- Package names this repository as its sourcecli2mcp names ronieneubauer/cli2mcp as sourcenpmjs.com/package/cli2mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-04-29github.com/ronieneubauer/cli2mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from cli2mcpPass
- No critical advisory in the package or its dependencies117 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcli2mcp
Status: v0.1 — early release. Stdio transport only. APIs may change before 1.0.
Expose any command-line binary as a Model Context Protocol tool by parsing its --help output and synthesizing a JSON Schema at startup. One command, no boilerplate.
Works with any MCP-compatible client — Claude Desktop, ChatGPT (via OpenAI Agents SDK), Cursor, Gemini CLI, Cline, Windsurf, Continue, Zed, and anything else that speaks the MCP stdio transport.
npx cli2mcp <command>
Why
Writing an MCP server for a CLI you already have is mechanical work: instantiate the SDK, register a tool, hand-write the input schema, marshal arguments, spawn the subprocess, format the output. Roughly 80–150 lines of TypeScript per binary, repeated forever as new tools come out.
cli2mcp does it in one command. The CLI's own --help is the source of truth for the schema — if rg adds a flag tomorrow, the AI sees it tomorrow without code changes.
Install
npm install -g cli2mcp
# or invoke without installing
npx cli2mcp <command>
Requires Node.js 22+.
Configure your MCP client
cli2mcp is launched by your client as a stdio subprocess. Add an entry per CLI you want to expose.
Claude Desktop
Config file location:
| OS | Path |
|---|---|
| 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"]
}
}
}
Restart Claude Desktop after editing.
Other clients
| Client | Config file | Format |
|---|---|---|
| ChatGPT (OpenAI Agents SDK) | MCPServerStdio parameter — see OpenAI Agents docs |
command: "npx", args: ["-y", "cli2mcp", "<cli>"] |
| Cursor | .cursor/mcp.json (project) or ~/.cursor/mcp.json (global) |
Same mcpServers block as above |
| Cline | VS Code → Cline → MCP Settings → cline_mcp_settings.json |
Same mcpServers block |
| Windsurf | ~/.codeium/windsurf/mcp_config.json |
Same mcpServers block |
| Gemini CLI | ~/.gemini/settings.json |
Same mcpServers block |
| Continue | ~/.continue/config.json → experimental.modelContextProtocolServers |
Same launcher |
| Zed | ~/.config/zed/settings.json → context_servers |
Same launcher |
| Any stdio-capable MCP client | per the client's docs | Same launcher: npx -y cli2mcp <command> |
Refer to each client's documentation for the exact config path on your platform — they evolve and are not guaranteed to match the table above.
Quick wins — copy-paste configs
Drop any of these into your client's mcpServers block (paths shown above per client). Each one wraps a popular CLI as an MCP tool an AI can call directly.
{
"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"]
}
}
}
Each CLI must already be installed and on
PATH.cli2mcpdoes not install them for you.
How it compares
| Approach | LOC per CLI | New flag handling | Maintenance |
|---|---|---|---|
| Hand-written MCP server (TypeScript SDK) | ~80–150 | manual schema edit | per-CLI release cycle |
| OpenAPI → MCP generators | n/a | requires an OpenAPI spec | does not cover arbitrary CLIs |
Wrapping bash / sh as a tool |
~10 | n/a — gives the AI a shell | unsafe, no schema, no sandbox |
cli2mcp <command> |
0 | automatic at next start | none — re-reads --help |
The closest neighbor is FastMCP's from_openapi — it does not cover arbitrary CLI binaries. As of April 2026 there is no other published tool that turns an arbitrary --help output into a typed MCP tool in one command.
Verified targets
These CLIs are covered by the test suite or have been manually exercised end-to-end:
| CLI | Status | Notes |
|---|---|---|
jq |
✅ tested | help-on-stderr correctly captured; stdin piping works |
ripgrep (rg) |
✅ tested | 90+ flags inferred; args positional handled |
curl |
✅ fixture | shape extraction validated against bundled fixture |
node |
✅ integration test | end-to-end MCP handshake + tools/call |
Other POSIX-style CLIs (e.g. ffmpeg, yt-dlp, pandoc, sqlite3, imagemagick) are expected to work but are not yet covered by tests. Report bugs in issues.
How --help becomes a JSON Schema
| Help fragment | MCP property |
|---|---|
--flag |
boolean |
--flag <value> / <file> / <path> |
string |
--flag <n> / <ms> / <size> |
number |
--flag <a|b|c> |
string enum with choices |
| Repeatable flag | array<string> |
| Positional args | args: array<string> |
Reserved input stdin |
string piped to subprocess stdin |
When parsing fails on an unconventional --help, cli2mcp falls back to a single variadic args positional so the tool is still usable — the model just gets a free-form argument list instead of typed flags.
Options
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
Piping stdin
Reserved input property stdin is piped to the subprocess:
{ "args": [".name"], "stdin": "{\"name\": \"cli2mcp\"}" }
How it works
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]
Non-zero exit → { isError: true, content: [{ type: "text", text: <stderr> }] } (unless --stderr drop).
Security
cli2mcp lets an AI agent invoke the CLIs you expose, with the arguments the agent chooses. You are responsible for what those CLIs can do on your machine.
Practical guidance:
- Only expose CLIs whose blast radius you accept.
jq,rg,pandocare mostly safe (read-only, deterministic).curl,ffmpeg --output,sqlite3,rm,kubectl,awsare not. - The AI is not sandboxed. A prompt injection attack could cause an exposed
curlto fetchevil.example.com, an exposedrmto delete files, etc. - Use
--cwdto constrain filesystem scope when wrapping CLIs that touch files. - Use
--envdeliberately. Do not pass through credentials the model shouldn't reach. - Never expose
sh,bash,zsh,python -c, or anything with eval semantics — that bypasses every safeguardcli2mcpprovides.
The schema-from-help design reduces the risk of malformed argv but does not eliminate the risk of misuse. Treat each exposed CLI as a delegated capability, not a sandbox.
Troubleshooting
The CLI has no --help flag.
cli2mcp will still start with a single args positional. The AI can pass arguments freely; you lose typed flag inference.
The schema came out empty / wrong.
Run cli2mcp <command> manually and inspect the tools/list response (use npx @modelcontextprotocol/inspector). The most common cause is non-standard help formatting (no --long-form flags, columns misaligned). Open an issue with the <command> --help output attached.
The subprocess hangs.
The default 60s timeout will kill it. Raise via --timeout. If your CLI is interactive (waits for a TTY), cli2mcp cannot help — pipe input via stdin instead.
Flag not being passed.
Set --stderr include (the default) and inspect the content[].text. If the flag isn't appearing in argv, the help parser failed to extract it — file an issue.
Contributing
Bug reports and patches welcome. Fixtures for new CLIs (test/fixtures/help/<cli>.txt + a shape test) are the highest-leverage contributions.
pnpm install
pnpm test # vitest
pnpm typecheck # tsc --noEmit
pnpm lint # biome check
Star history
If cli2mcp saved you an afternoon of writing MCP boilerplate, a star helps other people find it.
Author
Built by Ronie Neubauer — Principal Engineer, 22+ years shipping production systems.
- GitHub: @RonieNeubauer
- Blog: ronieneubauer.com
- Issues & ideas: github.com/RonieNeubauer/cli2mcp/discussions
License
MIT © 2026 Ronie Neubauer.
cli2mcp MCP questions
How do I add cli2mcp MCP to Claude Code?
Run claude mcp add cli2mcp -- npx -y cli2mcp in your terminal. Add --scope user to make it available in every project.
How do I add cli2mcp MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What happens if a CLI does not have a --help flag?
The server will still start but will fall back to a single variadic args positional, meaning the AI gets a free-form argument list instead of typed flags.
Does cli2mcp install the command-line tools for me?
No, the CLI must already be installed and available on your system's PATH.
Is the AI sandboxed when using this tool?
No, the AI is not sandboxed and can invoke any CLI you expose with arguments it chooses; you are responsible for the security implications.