codex-mcp-bridge

英語版

Claude Desktop 用の MCP サーバーで、共有の Codex app-server を介して既存の Codex スレッドに直接プロンプトを送信します。macOS、Windows、Linux で動作します。

codex exec（毎回新しいセッションを作成する方法）ではありません。Bridge は Codex の実際の app-server と JSON-RPC で通信するため、スレッドは履歴、cwd、モデル、rollout ファイルを保持します。

アーキテクチャ

Claude Desktop ──stdio──> codex-mcp-bridge ──WebSocket──> codex app-server (ws://127.0.0.1:8791)
                                                                  │
Codex TUI  ──codex --remote ws://127.0.0.1:8791───────────────────┘   (cùng app-server, cùng thread live)

• App-server はポート単位のシングルトンです。Bridge は http://127.0.0.1:8791/readyz をプローブし、まだ生きていなければデタッチで自動生成します（codex app-server --listen ws://127.0.0.1:8791）。この app-server は Bridge が終了した後も独立して動作し続けます。

• 同じ URL を指すすべてのクライアントは1 つの app-server を共有します。threadId による thread/resume は、新しいセッションを開くのではなく、実行中のスレッドに正しく再参加します。

• Bridge は WebSocket を 1 つだけ保持し、initialize を 1 回行い、threadId ごとに通知をルーティングするため、複数のスレッドを並行実行しても混線しません。

Related MCP server: webgpt MCP

ツール

send_to_codex_thread は追加で timeoutSec（デフォルト 240）、cwd、model、effort、openInApp（macOS — 送信前にアプリでスレッドを開いてライブで見る）を受け付けます。タイムアウトしてもターンはキャンセルされません。Bridge は取得できた内容を turnId とともに返します。続きは read_codex_thread で読むか、interrupt_codex_turn で停止します。

Claude Desktop へのインストール

npm install
node scripts/install-claude-desktop.mjs

スクリプトがプラットフォームを自動検出し、config ファイルがなければ作成し、既存のものはバックアップ（*.bak-<ngày>-codexbridge）して、既存のすべてのキーを保持します。

macOS での結果:

{
  "mcpServers": {
    "codex-bridge": {
      "command": "/Users/<user>/.local/node/v24.18.0/bin/node",
      "args": ["/Users/<user>/code/codex-mcp-bridge/src/index.mjs"],
      "env": {
        "CODEX_BIN": "/Users/<user>/.local/bin/codex",
        "CODEX_APP_SERVER_URL": "ws://127.0.0.1:8791"
      }
    }
  }
}

インストール後、Claude Desktop を再起動します。

codex バイナリの解決: Claude Desktop（および launchd）は PATH が切り詰められた状態で MCP サーバーを起動するため、codex が PATH 上にないことがよくあります。Bridge は CODEX_BIN → プラットフォームの既知のインストール場所 → PATH の順に探します。

macOS/Linux では、codex は shebang #!/usr/bin/env node を持つ Node スクリプトです。そのため Bridge は子プロセスに PATH（現在の node ディレクトリ + /opt/homebrew/bin + /usr/local/bin + システムディレクトリ）を再注入します。この手順がないと、app-server の spawn は shebang の時点で失敗します。

macOS

launchd で App-server をバックグラウンド実行

node scripts/install-launch-agent.mjs

~/Library/LaunchAgents/com.codex-mcp-bridge.app-server.plist を作成し（RunAtLoad + クラッシュ時の KeepAlive、ThrottleInterval 10 秒）、launchctl bootstrap gui/$UID を実行します。App-server はログイン時から起動しているため、Bridge が自分で spawn する必要はなく、スレッドは常にライブ状態です。

launchctl print gui/$UID/com.codex-mcp-bridge.app-server | head -20   # trạng thái
node scripts/install-launch-agent.mjs --uninstall                     # gỡ

ログ: ~/Library/Logs/codex-mcp-bridge/app-server.{out,err}.log。

Codex デスクトップアプリでスレッドを直接表示

macOS の Codex デスクトップアプリは /Applications/ChatGPT.app で、codex:// スキームを登録しています。Bridge は codex://threads/<threadId> を使って該当スレッドを開きます:

open_codex_thread { threadId: "01a0…", background: true }
send_to_codex_thread { threadId: "01a0…", prompt: "…", openInApp: true }

これは、タスクを依頼した人が Codex の作業をリアルタイムで確認できるようにする方法です。完了後に ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl を読み返す必要はありません。

macOS の制限事項

• Codex デスクトップアプリは stdio 経由で独自の app-server を起動し（ChatGPT.app/Contents/Resources/codex … app-server）、外部エンドポイントを受け付けません。アプリで開いたスレッドには Bridge 経由で送信できますが、ライブアタッチではなく rollout .jsonl からの再開メカニズムになります。デスクトップアプリでターン実行中のスレッドには送信しないでください — 2 つの app-server が同じ rollout に書き込むと履歴が壊れる可能性があります。先に list_codex_threads で status を確認し、idle/notLoaded のときだけ送信します。

• デュアルブート機の NTFS パーティション（/Volumes/...）にあるリポジトリは macOS では読み取り専用です — macOS は NTFS を読み取り専用でマウントします。実行と編集には APFS ボリュームに別のチェックアウト（例: ~/code/codex-mcp-bridge）を用意してください。

• codex app-server daemon start は transport unix:// とコントロールソケット ~/.codex/app-server-control/app-server-control.sock を使用します。Bridge はこの経路を使用しません（WebSocket とは異なるフレームプロトコルで、公開 API がありません）。常に ws:// で通信します。

環境変数

approval について: approval_policy が never 以外の場合、Codex はコマンド/パッチの承認を求めます。Claude Desktop の前に誰も座ってクリックするわけではないので、Bridge は CODEX_BRIDGE_APPROVAL に従って自動的に応答し、stderr にログを出力します。デフォルトの approve は ~/.codex/config.toml の approval_policy = "never" + sandbox_mode = "danger-full-access" という設定と一致します。sandbox を厳しくする場合は deny への変更を検討してください。

対話型 Codex セッションと app-server を共有する

同じエンドポイントを指す TUI を開くと、TUI のスレッドと Bridge のスレッドが同じものとして見えます:

codex --remote ws://127.0.0.1:8791

app-server を手動で実行する場合（Bridge の autostart に依存しない）:

codex app-server --listen ws://127.0.0.1:8791

テスト

npm run check

クイックチェック: Bridge を起動し、必要に応じて app-server を autostart し、スレッドを一覧表示します。

npm run smoke

スモークテストでは、新しいスレッドを作成し、2 つのターンを連続で送信して、Codex が前のターンのコードワードを覚えていることを確認します。つまり、スレッドが毎回新しいセッションではなく、実際に継続していることを確認します。

Claude 内から環境を確認するには、ツール codex_bridge_status を呼び出します。