mcp-convert を公開 — Claude Code の MCP 設定を Codex CLI にエージェントスキルで移行

はじめに

Claude Code と Codex CLI を併用している開発者が増えています。どちらも MCP（Model Context Protocol）サーバーに対応しており、Playwright、Firecrawl、GitHub MCP など同じツールを使えます。しかし、両者の MCP 設定形式はまったく異なります。

Claude Code は ~/.claude.json に JSON 形式で設定を保持し、Codex CLI は ~/.codex/config.toml に TOML 形式で設定を保持します。MCP サーバーを追加するたびに、両方の設定ファイルを手動で書き換える必要がありました。

この課題を解決するために、agent-skills に新しいスキル mcp-convert を追加しました。Claude Code の MCP 設定を Codex CLI 形式に自動変換するスキルです。

なぜ MCP 設定の移行が必要なのか？

MCP はエージェントに外部ツールを接続するためのプロトコルです。Claude Code でも Codex CLI でも MCP サーバーを使えますが、設定の管理方法が異なります。

Claude Code の設定（JSON）:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@anthropic/mcp-playwright"],
      "type": "stdio"
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx..."
      }
    }
  }
}

Codex CLI の設定（TOML）:

[mcp_servers.playwright]
command = "npx"
args = ["@anthropic/mcp-playwright"]
 
[mcp_servers.github]
command = "npx"
args = ["-y", "@modelcontextprotocol/server-github"]
 
[mcp_servers.github.env]
GITHUB_PERSONAL_ACCESS_TOKEN = "ghp_xxx..."

MCP サーバーが 2〜3 個なら手動でも問題ありませんが、10 個以上になると管理が破綻します。API キーを含む env 値の転記ミスも起こりやすくなります。

OpenAI の 公式ドキュメントによると、Codex は config.toml のセクション名が mcp_servers（アンダースコア）でなければならず、mcp-servers や mcpservers では設定がサイレントに無視されます。こうした細かな差異がヒューマンエラーの原因になります。

mcp-convert はどう動くのか？

mcp-convert は Python スクリプト（convert_claude_to_codex.py）を中心に構成されています。Claude Code の ~/.claude.json を読み取り、mcpServers ブロックの各サーバー定義を Codex CLI の形式に変換します。

変換の仕組み

スクリプトは以下のステップで動作します。

1. ソース読み込み: ~/.claude.json から mcpServers オブジェクトを抽出
2. サーバー解析: 各サーバーの type（stdio / http / sse / streamable_http）、command、args、env、url をパース
3. 変換: Claude 形式から Codex 形式に変換（JSON → TOML マッピング、env 値のコピー）
4. 出力: 選択されたモードに応じて dry-run 表示 / Codex に登録 / TOML 出力

対応するサーバータイプ

env 値（API キー等）は Claude の設定からそのまま Codex の設定にコピーされます。シークレットの暗号化や外部ストアへの保存は行わないため、設定ファイルのパーミッション管理はユーザーの責任です。

どうやって使うのか？

インストール

# agent-skills から mcp-convert だけをインストール
npx skills add anyoneanderson/agent-skills --skill mcp-convert -g -y
 
# 全スキルを一括インストール
npx skills add anyoneanderson/agent-skills -g -y

基本的な使い方

インストール後、エージェントに話しかけるだけで使えます。

> Claude の MCP を Codex に変換して
> convert Claude MCP to Codex
> MCP設定を移行

スキルが起動すると、以下の対話フローが進みます。

Step 1: サーバー検出

~/.claude.json を読み取り、登録されている MCP サーバーの一覧を表示します。

検出されたサーバー:
- playwright: type=stdio, env: なし
- github: type=stdio, env: GITHUB_PERSONAL_ACCESS_TOKEN
- firecrawl: type=stdio, env: FIRECRAWL_API_KEY

Step 2: 移行対象の選択

複数サーバーがある場合、どれを移行するか確認します。

移行するサーバーを選んでください:
- すべて移行（推奨）
- シークレットを含むサーバーのみ
- 手動で選択

Step 3: 実行モードの選択

実行モードを選んでください:
- dry-run（プレビューのみ）（推奨）
- apply（Codex に登録）
- export-toml（TOML 出力のみ）

コマンドラインでの直接実行

スキル経由ではなく、Python スクリプトを直接実行することもできます。

# プレビュー（変更なし）
python3 scripts/convert_claude_to_codex.py --mode dry-run
 
# 特定のサーバーだけ移行
python3 scripts/convert_claude_to_codex.py --mode apply --server github --server playwright
 
# 既存の設定を上書き
python3 scripts/convert_claude_to_codex.py --mode apply --overwrite
 
# TOML を標準出力に出力
python3 scripts/convert_claude_to_codex.py --mode export-toml

agent-skills の全体像

mcp-convert の追加により、agent-skills リポジトリには現在 7 つのスキルが含まれています。

仕様駆動開発スキル群（spec-*）に加えて、エージェント間の設定移行という新しいカテゴリのスキルが加わりました。

よくある質問

Q. Claude Code 以外のエージェントからの移行にも対応していますか？

A. 現時点では Claude Code（~/.claude.json）から Codex CLI への変換のみに対応しています。今後、Cursor や Gemini CLI など他のエージェント間の変換にも対応を検討しています。

Q. env に含まれる API キーはどう扱われますか？

A. Claude の設定ファイルから読み取った env 値は、そのまま平文で Codex の設定にコピーされます。暗号化や外部シークレットマネージャーへの保存は行いません。~/.codex/config.toml のファイルパーミッションを適切に設定してください。

Q. 既存の Codex MCP 設定は上書きされますか？

A. デフォルトでは、同名のサーバーが既に Codex に登録されている場合はスキップされます。--overwrite オプションを指定すると上書きします。まず --mode dry-run で確認してから --mode apply を実行することを推奨します。

Q. プロジェクト固有の MCP 設定も移行できますか？

A. 現在はトップレベルの ~/.claude.json のみを対象としています。プロジェクト固有の .claude.json に定義された MCP オーバーライドは個別に確認してください。

まとめ

mcp-convert は、Claude Code と Codex CLI を併用する開発者のための MCP 設定移行スキルです。

• ワンコマンドで移行: ~/.claude.json の MCP サーバー定義を Codex CLI 形式に自動変換
• 安全な 3 モード: dry-run でプレビュー → apply で適用 → export-toml で確認
• Agent Skills として実装: npx skills add でインストール、17 以上のエージェントで動作

マルチエージェント開発が当たり前になりつつある今、エージェント間の設定を手動で同期する手間は減らすべきコストです。mcp-convert がその一助になれば幸いです。

リポジトリ: github.com/anyoneanderson/agent-skills

ZenChAIne では、AI エージェントを活用した開発ツールやワークフローの研究・開発を続けています。フィードバックや Pull Request も歓迎です。

agent-skills をオープンソース公開 — AIエージェントによる仕様駆動開発の実践仕様駆動開発を AIエージェントのスキルとして実装した agent-skills をオープンソース公開しました。zench-aine.io

Agent Skills とは何か — AIエージェントに再利用可能なスキルを追加する仕組みSKILL.md フォーマットの仕組み、カスタムスラッシュコマンドとの違い、対応エージェント、自作方法を解説します。zench-aine.io

参考ソース

• Codex CLI - Model Context Protocol
• Codex CLI Configuration Reference
• agent-skills リポジトリ