cli2mcp

Статус: v0.1 — ранняя версия. Поддерживается только транспорт stdio. API может измениться до версии 1.0.

Превратите любую консольную утилиту в инструмент Model Context Protocol, анализируя её вывод --help и синтезируя JSON-схему при запуске. Одна команда, никакого шаблонного кода.

Работает с любым MCP-совместимым клиентом — Claude Desktop, ChatGPT (через OpenAI Agents SDK), Cursor, Gemini CLI, Cline, Windsurf, Continue, Zed и любым другим, поддерживающим транспорт MCP stdio.

npx cli2mcp <command>

Зачем это нужно

Написание MCP-сервера для уже имеющейся CLI-утилиты — это рутинная работа: инициализация SDK, регистрация инструмента, написание схемы ввода вручную, маршалинг аргументов, запуск подпроцесса, форматирование вывода. Примерно 80–150 строк TypeScript на каждый бинарный файл, и так каждый раз при появлении новых инструментов.

cli2mcp делает это одной командой. Собственный вывод --help утилиты является источником истины для схемы — если завтра в rg добавят флаг, ИИ увидит его завтра без изменения кода.

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

Расположение файла конфигурации:

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

После редактирования перезапустите Claude Desktop.

Другие клиенты

Обратитесь к документации каждого клиента для уточнения пути к конфигурации на вашей платформе — они меняются и не гарантированно соответствуют таблице выше.

Быстрый старт — готовые конфигурации

Вставьте любой из этих примеров в блок mcpServers вашего клиента (пути указаны выше для каждого клиента). Каждый из них оборачивает популярную CLI-утилиту в 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 не устанавливает их за вас.

Сравнение подходов

Ближайший аналог — from_openapi из FastMCP, но он не работает с произвольными CLI-бинарниками. По состоянию на апрель 2026 года нет другого опубликованного инструмента, который превращает произвольный вывод --help в типизированный MCP-инструмент одной командой.

Проверенные цели

Эти CLI-утилиты покрыты набором тестов или были проверены вручную:

Другие POSIX-совместимые CLI (например, ffmpeg, yt-dlp, pandoc, sqlite3, imagemagick) должны работать, но еще не покрыты тестами. Сообщайте об ошибках в issues.

Как --help превращается в JSON Schema

Если парсинг нестандартного --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 позволяет ИИ-агенту вызывать CLI-утилиты, которые вы предоставляете, с аргументами, выбранными агентом. Вы несете ответственность за то, что эти утилиты могут сделать на вашем компьютере.

Практические рекомендации:

• Предоставляйте доступ только к тем CLI, радиус поражения которых вы принимаете. jq, rg, pandoc в основном безопасны (только чтение, детерминированы). curl, ffmpeg --output, sqlite3, rm, kubectl, aws — нет.

• ИИ не находится в песочнице. Атака через инъекцию промпта может заставить curl обратиться к evil.example.com, rm — удалить файлы и т.д.

• Используйте --cwd для ограничения области файловой системы при оборачивании CLI, работающих с файлами.

• Используйте --env осознанно. Не передавайте учетные данные, к которым модель не должна иметь доступа.

• Никогда не предоставляйте доступ к sh, bash, zsh, python -c или чему-либо с семантикой eval — это обходит все меры защиты, предоставляемые cli2mcp.

Дизайн «схема из справки» снижает риск неправильного формирования argv, но не устраняет риск злоупотребления. Относитесь к каждой предоставленной CLI-утилите как к делегированной возможности, а не как к песочнице.

Устранение неполадок

У CLI нет флага --help. cli2mcp все равно запустится с одним позиционным аргументом args. ИИ сможет свободно передавать аргументы; вы теряете типизацию флагов.

Схема получилась пустой или неверной. Запустите cli2mcp <command> вручную и проверьте ответ tools/list (используйте npx @modelcontextprotocol/inspector). Самая частая причина — нестандартное форматирование справки (отсутствие флагов --long-form, смещенные столбцы). Откройте issue, приложив вывод <command> --help.

Подпроцесс зависает. Тайм-аут по умолчанию в 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

История звезд

Если cli2mcp сэкономил вам время на написании шаблонного кода MCP, звезда поможет другим найти этот инструмент.

Автор

Создано Ronie Neubauer — ведущий инженер, 22+ года разработки производственных систем.

• GitHub: @RonieNeubauer

• Блог: ronieneubauer.com

• Вопросы и идеи: github.com/RonieNeubauer/cli2mcp/discussions

Лицензия

MIT © 2026 Ronie Neubauer.