cli2mcp

Estado: v0.1 — lanzamiento inicial. Solo transporte stdio. Las APIs pueden cambiar antes de la versión 1.0.

Expón cualquier binario de línea de comandos como una herramienta del Protocolo de Contexto de Modelo analizando su salida --help y sintetizando un JSON Schema al iniciar. Un comando, sin código repetitivo (boilerplate).

Funciona con cualquier cliente compatible con MCP — Claude Desktop, ChatGPT (vía OpenAI Agents SDK), Cursor, Gemini CLI, Cline, Windsurf, Continue, Zed y cualquier otra cosa que utilice el transporte stdio de MCP.

npx cli2mcp <command>

Por qué

Escribir un servidor MCP para una CLI que ya tienes es un trabajo mecánico: instanciar el SDK, registrar una herramienta, escribir a mano el esquema de entrada, organizar los argumentos, generar el subproceso, formatear la salida. Aproximadamente 80–150 líneas de TypeScript por binario, repetidas una y otra vez a medida que salen nuevas herramientas.

cli2mcp lo hace en un solo comando. El propio --help de la CLI es la fuente de verdad para el esquema; si rg añade una bandera mañana, la IA la verá mañana sin cambios en el código.

Related MCP server: MCP-OpenAPI

Instalación

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

Requiere Node.js 22+.

Configura tu cliente MCP

cli2mcp es ejecutado por tu cliente como un subproceso stdio. Añade una entrada por cada CLI que desees exponer.

Claude Desktop

Ubicación del archivo de configuración:

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

Reinicia Claude Desktop después de editar.

Otros clientes

Consulta la documentación de cada cliente para conocer la ruta de configuración exacta en tu plataforma; estas evolucionan y no se garantiza que coincidan con la tabla anterior.

Victorias rápidas — copiar y pegar configuraciones

Coloca cualquiera de estos en el bloque mcpServers de tu cliente (las rutas se muestran arriba por cliente). Cada uno envuelve una CLI popular como una herramienta MCP que una IA puede llamar directamente.

{
  "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"]
    }
  }
}

Cada CLI debe estar ya instalada y en el PATH. cli2mcp no las instala por ti.

Comparativa

El vecino más cercano es from_openapi de FastMCP; no cubre binarios CLI arbitrarios. A fecha de abril de 2026, no existe ninguna otra herramienta publicada que convierta una salida --help arbitraria en una herramienta MCP tipada en un solo comando.

Objetivos verificados

Estas CLIs están cubiertas por el conjunto de pruebas o han sido probadas manualmente de extremo a extremo:

Se espera que otras CLIs de estilo POSIX (ej. ffmpeg, yt-dlp, pandoc, sqlite3, imagemagick) funcionen, pero aún no están cubiertas por pruebas. Informa de errores en issues.

Cómo --help se convierte en un JSON Schema

Cuando el análisis falla en un --help poco convencional, cli2mcp recurre a un único args posicional variádico para que la herramienta siga siendo utilizable; el modelo simplemente obtiene una lista de argumentos de forma libre en lugar de banderas tipadas.

Opciones

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

Canalización de stdin

La propiedad de entrada reservada stdin se canaliza al subproceso:

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

Cómo funciona

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]

Salida distinta de cero → { isError: true, content: [{ type: "text", text: <stderr> }] } (a menos que se use --stderr drop).

Seguridad

cli2mcp permite que un agente de IA invoque las CLIs que expones, con los argumentos que el agente elija. Tú eres responsable de lo que esas CLIs puedan hacer en tu máquina.

Guía práctica:

• Solo expón CLIs cuyo radio de explosión aceptes. jq, rg, pandoc son mayormente seguras (solo lectura, deterministas). curl, ffmpeg --output, sqlite3, rm, kubectl, aws no lo son.

• La IA no está en un sandbox. Un ataque de inyección de prompt podría hacer que un curl expuesto obtenga evil.example.com, un rm expuesto borre archivos, etc.

• Usa --cwd para limitar el alcance del sistema de archivos al envolver CLIs que tocan archivos.

• Usa --env deliberadamente. No pases credenciales a las que el modelo no debería acceder.

• Nunca expongas sh, bash, zsh, python -c o cualquier cosa con semántica de eval — eso evita todas las salvaguardas que proporciona cli2mcp.

El diseño de esquema desde la ayuda reduce el riesgo de argv mal formado pero no elimina el riesgo de uso indebido. Trata cada CLI expuesta como una capacidad delegada, no como un sandbox.

Solución de problemas

La CLI no tiene bandera --help. cli2mcp seguirá iniciando con un único args posicional. La IA puede pasar argumentos libremente; pierdes la inferencia de banderas tipadas.

El esquema salió vacío / incorrecto. Ejecuta cli2mcp <command> manualmente e inspecciona la respuesta de tools/list (usa npx @modelcontextprotocol/inspector). La causa más común es un formato de ayuda no estándar (sin banderas --long-form, columnas desalineadas). Abre un issue con la salida de <command> --help adjunta.

El subproceso se cuelga. El tiempo de espera predeterminado de 60s lo terminará. Auméntalo mediante --timeout. Si tu CLI es interactiva (espera un TTY), cli2mcp no puede ayudar; canaliza la entrada a través de stdin en su lugar.

La bandera no se está pasando. Establece --stderr include (el valor predeterminado) e inspecciona el content[].text. Si la bandera no aparece en argv, el analizador de ayuda no pudo extraerla; abre un issue.

Contribución

Los informes de errores y parches son bienvenidos. Los fixtures para nuevas CLIs (test/fixtures/help/<cli>.txt + una prueba de forma) son las contribuciones de mayor impacto.

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

Historial de estrellas

Si cli2mcp te ahorró una tarde escribiendo boilerplate de MCP, una estrella ayuda a otras personas a encontrarlo.

Autor

Creado por Ronie Neubauer — Ingeniero Principal, más de 22 años entregando sistemas de producción.

• GitHub: @RonieNeubauer

• Blog: ronieneubauer.com

• Problemas e ideas: github.com/RonieNeubauer/cli2mcp/discussions

Licencia

MIT © 2026 Ronie Neubauer.