cli2mcp

상태: v0.1 — 초기 릴리스. Stdio 전송만 지원합니다. 1.0 이전에는 API가 변경될 수 있습니다.

명령줄 바이너리의 --help 출력을 파싱하고 시작 시 JSON 스키마를 합성하여 모든 명령줄 바이너리를 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 인스턴스화, 도구 등록, 입력 스키마 수동 작성, 인수 마샬링, 하위 프로세스 생성, 출력 형식 지정 등이 필요합니다. 바이너리당 약 80~150줄의 TypeScript 코드가 필요하며, 새로운 도구가 나올 때마다 반복됩니다.

cli2mcp는 이를 단일 명령으로 수행합니다. CLI 자체의 --help가 스키마의 진실 공급원(source of truth)이므로, 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

구성 파일 위치:

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

편집 후 Claude Desktop을 다시 시작하세요.

기타 클라이언트

플랫폼별 정확한 구성 경로는 각 클라이언트의 문서를 참조하세요. 경로는 변경될 수 있으며 위 표와 일치하지 않을 수 있습니다.

빠른 시작 — 구성 복사 및 붙여넣기

다음 중 하나를 클라이언트의 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는 이를 대신 설치해주지 않습니다.

비교

가장 유사한 것은 FastMCP의 from_openapi이지만, 이는 임의의 CLI 바이너리를 다루지 못합니다. 2026년 4월 현재, 임의의 --help 출력을 단일 명령으로 유형화된 MCP 도구로 변환하는 다른 공개 도구는 없습니다.

검증된 대상

다음 CLI는 테스트 제품군에 포함되어 있거나 수동으로 전체 테스트를 거쳤습니다:

기타 POSIX 스타일 CLI(ffmpeg, yt-dlp, pandoc, sqlite3, imagemagick 등)도 작동할 것으로 예상되지만 아직 테스트가 완료되지 않았습니다. 버그는 이슈에 보고해주세요.

--help가 JSON 스키마가 되는 과정

비표준 --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]

0이 아닌 종료 코드 → { 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가 제공하는 모든 안전장치를 우회합니다.

help-from-schema 설계는 잘못된 argv의 위험을 줄여주지만, 오용의 위험을 제거하지는 않습니다. 노출된 각 CLI를 샌드박스가 아닌 위임된 기능으로 취급하세요.

문제 해결

CLI에 --help 플래그가 없습니다. cli2mcp는 단일 args 위치 인수로 시작합니다. AI는 인수를 자유롭게 전달할 수 있지만, 유형화된 플래그 추론은 사용할 수 없습니다.

스키마가 비어 있거나 잘못되었습니다. cli2mcp <command>를 수동으로 실행하고 tools/list 응답을 검사하세요(npx @modelcontextprotocol/inspector 사용). 가장 흔한 원인은 비표준 도움말 형식(긴 형식 플래그 없음, 열 정렬 불량)입니다. <command> --help 출력을 첨부하여 이슈를 열어주세요.

하위 프로세스가 멈춥니다. 기본 60초 타임아웃이 프로세스를 종료합니다. --timeout을 통해 늘리세요. CLI가 대화형(TTY 대기)인 경우 cli2mcp는 도움을 줄 수 없습니다. 대신 stdin을 통해 입력을 파이핑하세요.

플래그가 전달되지 않습니다. --stderr include(기본값)를 설정하고 content[].text를 검사하세요. 플래그가 argv에 나타나지 않으면 도움말 파서가 이를 추출하지 못한 것이므로 이슈를 제기하세요.

기여

버그 보고 및 패치를 환영합니다. 새로운 CLI에 대한 픽스처(test/fixtures/help/<cli>.txt + 형태 테스트)는 가장 큰 도움이 되는 기여입니다.

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

Star 기록

cli2mcp가 MCP 보일러플레이트를 작성하는 시간을 절약해주었다면, 별표를 눌러 다른 사람들이 찾을 수 있도록 도와주세요.

작성자

Ronie Neubauer 제작 — 수석 엔지니어, 22년 이상 프로덕션 시스템 구축.

• GitHub: @RonieNeubauer

• 블로그: ronieneubauer.com

• 이슈 및 아이디어: github.com/RonieNeubauer/cli2mcp/discussions

라이선스

MIT © 2026 Ronie Neubauer.