cli2mcp

cli2mcp

ステータス： 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>

---

理由

すでに使っている CLI 用の MCP サーバーを作成するのは、機械的な作業です。SDK のインスタンス化、ツールの登録、入力スキーマの手書き、引数の変換、サブプロセスの起動、出力の整形などが必要になります。バイナリごとにおよそ 80〜150 行の TypeScript が必要で、新しいツールが登場するたびに繰り返すことになります。

cli2mcp を使えば、コマンドひとつで実現できます。スキーマの信頼できる情報源は CLI 自身の --help です。たとえば明日 rg にフラグが追加されれば、コードを変更しなくても、AI は明日にはそのフラグを認識します。

---

インストール

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

Node.js 22 以降が必要です。

---

MCP クライアントの設定

cli2mcp は、stdio サブプロセスとしてクライアントから起動されます。公開したい CLI ごとにエントリーを追加してください。

Claude Desktop

設定ファイルの場所：

OS	パス
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 を MCP ツールとしてラップし、AI から直接呼び出せるようにします。

{
  "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 をインストールしません。

---

比較

アプローチ	CLI あたりの LOC	新しいフラグへの対応	メンテナンス
手書きの MCP サーバー（TypeScript SDK）	~80–150	スキーマを手動で編集	CLI ごとのリリースサイクル
OpenAPI → MCP ジェネレーター	n/a	OpenAPI 仕様が必要	任意の CLI には対応しない
bash / sh をツールとしてラップ	~10	n/a — AI にシェルを提供	安全でなく、スキーマもサンドボックスもない
cli2mcp <command>	0	次回起動時に自動対応	不要 — --help を再読み込み

最も近い類似ツールは FastMCP の from_openapi ですが、任意の CLI バイナリには対応していません。2026 年 4 月現在、任意の --help 出力を 1 つのコマンドで型付き MCP ツールに変換する、ほかの公開ツールはありません。

---

動作確認済みの対象

以下の CLI はテストスイートでカバーされているか、エンドツーエンドで手動検証済みです。

CLI	状態	備考
jq	✅ テスト済み	stderr のヘルプを正しく取得。stdin のパイプ入力が動作
ripgrep (rg)	✅ テスト済み	90 個以上のフラグを推定。args の位置引数に対応
curl	✅ フィクスチャ	同梱フィクスチャに対して形状の抽出を検証済み
node	✅ 統合テスト	MCP ハンドシェイクと tools/call をエンドツーエンドで検証

ほかの POSIX スタイルの CLI（例：ffmpeg、yt-dlp、pandoc、sqlite3、imagemagick）も動作することが期待されますが、まだテストではカバーされていません。不具合はイシューで報告してください。

---

--help が JSON Schema になる仕組み

ヘルプの断片	MCP プロパティ
--flag	boolean
--flag <value> / <file> / <path>	string
--flag <n> / <ms> / <size>	number
--flag <a|b|c>	選択肢を持つ string の enum
繰り返し指定できるフラグ	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 を使うと、公開した CLI を AI エージェントが、エージェント自身が選んだ引数で実行できます。それらの 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 の出力を添えて、イシューを作成してください。

サブプロセスがハングします。 デフォルトの 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

---

スター履歴

cli2mcp によって MCP の定型コードを書く時間を数時間節約できたなら、スターを付けると、ほかの人にも見つけてもらいやすくなります。

---

作者

Ronie Neubauer が開発しました — プリンシパルエンジニアとして、22 年以上にわたり本番システムを開発・提供しています。

• GitHub: @RonieNeubauer
• ブログ: ronieneubauer.com
• イシューとアイデア: github.com/RonieNeubauer/cli2mcp/discussions

---

ライセンス

MIT © 2026 Ronie Neubauer.