mcp2cli

あらゆる MCP サーバー、OpenAPI スペック、GraphQL エンドポイントをランタイムで CLI に変換します。コード生成不要。

インストール

# インストール不要で直接実行
uvx mcp2cli --help

# またはインストール
pip install mcp2cli

コアワークフロー

1. 接続 ソース (MCP サーバー、OpenAPI スペック、GraphQL エンドポイント) に接続
2. 発見 --list で利用可能なコマンドを発見 (--search でフィルタリング可能)
3. 検査 特定のコマンドを <command> --help で検査
4. 実行 コマンドをフラグとともに実行

# HTTP 上の MCP
mcp2cli --mcp https://mcp.example.com/sse --list
mcp2cli --mcp https://mcp.example.com/sse create-task --help
mcp2cli --mcp https://mcp.example.com/sse create-task --title "Fix bug"

# stdio 上の MCP
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" --list
mcp2cli --mcp-stdio "npx @modelcontextprotocol/server-filesystem /tmp" read-file --path /tmp/hello.txt

# OpenAPI スペック (リモートまたはローカル、JSON または YAML)
mcp2cli --spec https://petstore3.swagger.io/api/v3/openapi.json --list
mcp2cli --spec ./openapi.json --base-url https://api.example.com list-pets --status available

# GraphQL エンドポイント
mcp2cli --graphql https://api.example.com/graphql --list
mcp2cli --graphql https://api.example.com/graphql users --limit 10
mcp2cli --graphql https://api.example.com/graphql create-user --name "Alice"

CLI リファレンス

mcp2cli [global options] <subcommand> [command options]

ソース (相互排他的、1 つ必須):
  --spec URL|FILE       OpenAPI スペック (JSON または YAML、ローカルまたはリモート)
  --mcp URL             MCP サーバー URL (HTTP/SSE)
  --mcp-stdio CMD       MCP サーバーコマンド (stdio トランスポート)
  --graphql URL         GraphQL エンドポイント URL

オプション:
  --auth-header K:V       HTTP ヘッダー (繰り返し可能、値は env:/file: プリフィックスをサポート)
  --base-url URL          スペックからの基本 URL をオーバーライド
  --transport TYPE        MCP HTTP トランスポート: auto|sse|streamable (デフォルト: auto)
  --env KEY=VALUE         stdio サーバープロセスの環境変数 (繰り返し可能)
  --oauth                 OAuth を有効化 (認可コード + PKCE フロー)
  --oauth-client-id ID    OAuth クライアント ID (env:/file: プリフィックスをサポート)
  --oauth-client-secret S OAuth クライアントシークレット (env:/file: プリフィックスをサポート)
  --oauth-scope SCOPE     リクエストする OAuth スコープ
  --cache-key KEY         カスタムキャッシュキー
  --cache-ttl SECONDS     キャッシュ TTL (デフォルト: 3600)
  --refresh               キャッシュをバイパス
  --list                  利用可能なサブコマンドをリスト表示
  --search PATTERN        ツールを名前または説明で検索 (--list を暗示)
  --fields FIELDS         GraphQL 選択セットをオーバーライド (例: "id name email")
  --pretty                JSON 出力をきれいに印字
  --raw                   レスポンスボディを生出力
  --toon                  TOON として出力をエンコード (LLM 向けトークン効率的)
  --head N                出力を最初の N レコードに制限 (配列)
  --version               バージョンを表示

Bake モード:
  bake create NAME [opts]   接続設定を名前付きツールとして保存
  bake list                 すべての baked ツールをリスト表示
  bake show NAME            設定を表示 (シークレットはマスク)
  bake update NAME [opts]   baked ツールを更新
  bake remove NAME          baked ツールを削除
  bake install NAME         ~/.local/bin ラッパースクリプトを作成
  @NAME [args]              baked ツールを実行 (例: mcp2cli @petstore --list)

サブコマンドとフラグはソースから動的に生成されます。

パターン

認証

シークレットには常に env: または file: プリフィックスを使用 — CLI フラグにリテラル値として認証情報を渡さないでください。リテラル値はプロセスリストとシェル履歴に表示されます。

# 環境変数からシークレット (推奨 — プロセスリストでの露出を回避)
mcp2cli --spec ./spec.json --auth-header "Authorization:env:API_TOKEN" list-items

# ファイルからシークレット
mcp2cli --mcp https://mcp.example.com/sse \
  --auth-header "x-api-key:file:/run/secrets/api_key" \
  search --query "test"

OAuth 認証 (MCP HTTP のみ)

# 認可コード + PKCE (ブラウザを開く)
mcp2cli --mcp https://mcp.example.com/sse --oauth --list

# クライアントクレデンシャル (マシン間)
mcp2cli --mcp https://mcp.example.com/sse \
  --oauth-client-id env:OAUTH_CLIENT_ID --oauth-client-secret env:OAUTH_CLIENT_SECRET \
  search --query "test"

# スコープ付き
mcp2cli --mcp https://mcp.example.com/sse --oauth --oauth-scope "read write" --list

トークンは ~/.cache/mcp2cli/oauth/ にキャッシュされ、自動的にリフレッシュされます。

トランスポート選択 (MCP HTTP のみ)

# デフォルト: streamable HTTP を試して、SSE にフォールバック
mcp2cli --mcp https://mcp.example.com/sse --list

# SSE トランスポートを強制 (streamable HTTP の試行をスキップ)
mcp2cli --mcp https://mcp.example.com/sse --transport sse --list

# Streamable HTTP を強制 (SSE フォールバックなし)
mcp2cli --mcp https://mcp.example.com/sse --transport streamable --list

GraphQL

# クエリとミューテーションを発見
mcp2cli --graphql https://api.example.com/graphql --list

# クエリを実行
mcp2cli --graphql https://api.example.com/graphql users --limit 10

# ミューテーションを実行
mcp2cli --graphql https://api.example.com/graphql create-user --name "Alice" --email "alice@example.com"

# 自動生成された選択セットをオーバーライド
mcp2cli --graphql https://api.example.com/graphql users --fields "id name email"

# 認証付き
mcp2cli --graphql https://api.example.com/graphql --auth-header "Authorization:env:API_TOKEN" users

ツール検索

# ツールを名前または説明でフィルタリング (大文字小文字を区別しない)
mcp2cli --mcp https://mcp.example.com/sse --search "task"
mcp2cli --spec ./openapi.json --search "create"
mcp2cli --graphql https://api.example.com/graphql --search "user"

--search は --list を暗示 — マッチしたツールのみを表示します。

標準入力から JSON ボディで POST

echo '{"name": "Fido", "tag": "dog"}' | mcp2cli --spec ./spec.json create-pet --stdin

マルチパートファイルアップロード

OpenAPI スペックが multipart/form-data を format: binary フィールドで宣言する場合、mcp2cli はそれらをファイルパス CLI 引数として公開します:

# ファイルをアップロード — バイナリフィールドはローカルファイルパスを受け入れます
mcp2cli --spec ./spec.json upload-image --file /path/to/photo.png --caption "My photo"

# 同じマルチパートスキーマ内の非バイナリフィールドは通常フラグになります
mcp2cli --spec ./spec.json upload-image --file ./image.jpg --title "Cover" --alt-text "A sunset"

ファイルパラメータは --help 出力に (file path) と表示されます。MIME タイプはファイル拡張子から自動検出されます。

stdio サーバーの環境変数

mcp2cli --mcp-stdio "node server.js" --env API_KEY=env:API_SECRET_KEY --env DEBUG=1 search --query "test"

Bake モード — 保存された設定

接続設定を名前付き設定として保存して、フラグの繰り返しを回避します:

# Baked ツールを作成
mcp2cli bake create petstore --spec https://api.example.com/spec.json \
  --exclude "delete-*,update-*" --methods GET,POST --cache-ttl 7200

mcp2cli bake create mygit --mcp-stdio "npx @mcp/github" \
  --include "search-*,list-*" --exclude "delete-*"

# @ プリフィックスで使用
mcp2cli @petstore --list
mcp2cli @petstore list-pets --limit 10

# 管理
mcp2cli bake list
mcp2cli bake show petstore
mcp2cli bake update petstore --cache-ttl 3600
mcp2cli bake remove petstore
mcp2cli bake install petstore    # ~/.local/bin/petstore ラッパーを作成

フィルタオプション: --include (glob ホワイトリスト)、--exclude (glob ブラックリスト)、--methods (HTTP メソッド、OpenAPI のみ)。

設定は ~/.config/mcp2cli/baked.json に保存されます (MCP2CLI_CONFIG_DIR でオーバーライド可能)。

キャッシング

スペックと MCP ツールリストは ~/.cache/mcp2cli/ にキャッシュされます (1h TTL)。ローカルファイルはキャッシュされません。

mcp2cli --spec https://api.example.com/spec.json --refresh --list    # 強制リフレッシュ
mcp2cli --spec https://api.example.com/spec.json --cache-ttl 86400 --list  # 24h TTL

TOON 出力 (LLM 向けトークン効率的)

mcp2cli --mcp https://mcp.example.com/sse --toon list-tags

大規模で均一な配列に最適 — JSON より 40～60% トークンが少なくなります。

--head で大きなレスポンスを切り詰め

# 潜在的に巨大なデータセットから最初の 3 レコードをプレビュー
mcp2cli --spec ./spec.json list-records --head 3 --pretty

--head N は JSON 配列を最初の N 要素にスライスします。超大型フィールド (例: geo_shape ポリゴン ~200KB/レコード) を含むデータセットに便利です。

セキュリティ

• 認証情報: シークレットには常に env: または file: プリフィックスを使用 — リテラルトークンやキーをコマンドに埋め込まないでください。env: プリフィックスは環境変数から読み込み、file: はファイルパスから読み込みます。
• 信頼境界: mcp2cli はユーザーが指定したリモート API と MCP サーバーに接続します。外部ソースからのレスポンスを信頼できないものとして扱い、操作前にデータを検証してください。
• Baked 設定: bake show は出力でシークレットをマスクします。Baked 設定はローカルの ~/.config/mcp2cli/baked.json に保存されます — このファイルを適切に保護してください。

API からスキルを生成

ユーザーが MCP サーバー、OpenAPI スペック、GraphQL エンドポイントからスキルを作成するよう求めた場合、このワークフローに従います:

1. 発見 すべての利用可能なコマンドを発見:

   uvx mcp2cli --mcp https://target.example.com/sse --list
   

2. 検査 各コマンドのパラメータを理解するために検査:

   uvx mcp2cli --mcp https://target.example.com/sse <command> --help
   

3. テスト 主要なコマンドを試し、エッジケースを探査:

   uvx mcp2cli --mcp https://target.example.com/sse <command> --param value
   

   特に以下をテスト:

   • 大規模レスポンス: --head 3 でプレビュー — 超大型出力を生成するフィールドがある (例: geo_shape、埋め込みブロブ)?
   • 日時フィールド: API がどのフォーマットを予期している (ISO 8601、Unix タイムスタンプ、date'2022' のようなカスタム構文)?
   • ページネーション: API がすべての結果を返すか、--offset/--limit が必要?
   • エラーメッセージ: 無効なパラメータでどうなる? エラーは有益?
   • バイナリ vs テキストレスポンス: エンドポイントが非 JSON (xlsx、parquet、画像) を返す?
   • スコープの混乱: データは予想より多い (例: 地域データを予期しているのに国家データを取得)?

4. Bake スキルがフラグを繰り返す必要がないように接続設定を保存:

   uvx mcp2cli bake create myapi \
     --mcp https://target.example.com/sse \
     --auth-header "Authorization:Bearer env:MYAPI_TOKEN" \
     --exclude "delete-*" --methods GET,POST
   

5. インストール ラッパーをスキルのスクリプトディレクトリにインストール:

   uvx mcp2cli bake install myapi --dir .claude/skills/myapi/scripts/
   

6. SKILL.md を作成 .claude/skills/myapi/ に、別の AI エージェントがこの API を使用する方法を教えるもの。SKILL.md は --help 出力を超える必要があります — テストと読書によってのみ学べる知識に焦点を当てます。

   Frontmatter:

   ---
   name: myapi
   description: MyAPI サービスと対話
   allowed-tools: Bash(bash *)
   ---
   

   コアワークフロー (発見 + 実行):

   # 利用可能なコマンドをリスト表示
   ${CLAUDE_SKILL_DIR}/scripts/myapi --list
   # コマンドのヘルプを取得
   ${CLAUDE_SKILL_DIR}/scripts/myapi <command> --help
   # コマンドを実行
   ${CLAUDE_SKILL_DIR}/scripts/myapi <command> --param value --pretty
   

   クエリの前にチェック — 意思決定フレームワークを含める:

   • どのデータセット/リソースをターゲットにしている?
   • ページネーションが必要? (--offset、--limit)
   • 除外または切り詰めすべき大規模出力を生成するフィールドがある? (--head)
   • このエンドポイントはどの日付/フィルタ形式を予期している?

   アンチパターン & 落とし穴 — テスト中に発見されたすべてのサプライズを文書化:

   • 日付構文の癖 (例: date'2022' vs "2022")
   • 超大型出力を生成するフィールド (例: geo_shape → --head で結果を制限)
   • エンドポイント間のパラメータ名の不一貫性
   • スコープ/フィルタリングの混乱 (例: データセットは地域データだけでなく国家データを含む)
   • バイナリエクスポート破損リスク (例: バイナリ形式をテキストエンコーディング経由でパイプしない)

   出力処理 — --pretty で読みやすい JSON、--head で結果を制限、または jq にパイプしてフィルタリング:

   # 結果をきれいに印字
   ${CLAUDE_SKILL_DIR}/scripts/myapi list-records --pretty
   # 大規模データセットを制限
   ${CLAUDE_SKILL_DIR}/scripts/myapi list-records --head 5
   # jq でフィルタリング (パイプ)
   ${CLAUDE_SKILL_DIR}/scripts/myapi list-records | jq '.[].name'
   

   エクスポート形式 (API が複数の出力タイプをサポートしている場合):

   • サポートされている形式をリスト表示 (JSON、CSV、xlsx、parquet など)
   • テキト安全 vs バイナリをメモ
   • バイナリ形式の場合: ${CLAUDE_SKILL_DIR}/scripts/myapi export --format xlsx --raw > output.xlsx

   知識差分原則: --help からのパラメータリスティングを重複させないでください。代わりに、一般的なタスクで実際に重要なパラメータ、デフォルト動作が驚くべきもの、機能しない組み合わせ、レート制限またはレスポンスサイズ制限を文書化します。

生成されたスキルは mcp2cli を実行層として使用します — baked ラッパースクリプトはすべての接続詳細を処理するため、SKILL.md は清潔でポータブルなままです。