codex-mcp-bridge

Englische Version

MCP-Server für Claude Desktop, um Prompts direkt in einen bestehenden Codex-Thread zu senden – über einen gemeinsamen Codex-App-Server. Läuft auf macOS, Windows und Linux.

Nicht codex exec (das jedes Mal eine neue Sitzung erstellt). Die Bridge spricht JSON-RPC mit dem echten Codex-App-Server, daher behält der Thread seine Historie, cwd, Modell und Rollout-Datei.

Architektur

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)

• Der App-Server ist ein Singleton pro Port. Die Bridge prüft http://127.0.0.1:8791/readyz; falls er nicht läuft, startet sie ihn selbst als eigenen Prozess (codex app-server --listen ws://127.0.0.1:8791), und dieser App-Server läuft nach dem Beenden der Bridge unabhängig weiter.

• Alle Clients, die auf dieselbe URL zeigen, verwenden einen gemeinsamen App-Server → thread/resume mit threadId tritt wieder in den laufenden Thread ein, anstatt eine neue Sitzung zu öffnen.

• Die Bridge hält genau eine WebSocket-Verbindung, führt initialize einmal aus und leitet Benachrichtigungen anhand der threadId weiter, sodass mehrere parallele Threads sich nicht vermischen.

Related MCP server: webgpt MCP

Tools

send_to_codex_thread akzeptiert außerdem timeoutSec (Standard 240), cwd, model, effort und openInApp (macOS – öffnet den Thread vor dem Senden in der App, um live zuzusehen). Wenn das Zeitlimit abläuft, wird der Turn nicht abgebrochen – die Bridge gibt die bereits gesammelten Daten zusammen mit turnId zurück. Weiterlesen mit read_codex_thread oder stoppen mit interrupt_codex_turn.

Installation in Claude Desktop

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

Das Skript erkennt die Plattform selbst, erstellt die Config-Datei, falls sie nicht existiert, sichert die alte Version (*.bak-<Datum>-codexbridge) und behält alle vorhandenen Schlüssel bei:

Ergebnis auf 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 nach der Installation neu starten.

Resolve des codex-Binaries: Claude Desktop (und launchd) starten den MCP-Server mit einem gekürzten PATH, daher ist codex normalerweise nicht im PATH. Die Bridge sucht in dieser Reihenfolge – CODEX_BIN → bekannte Installationsorte der Plattform → PATH:

Auf macOS/Linux ist codex ein Node-Skript mit Shebang #!/usr/bin/env node. Die Bridge setzt deshalb für den Kindprozess zusätzlich PATH (aktuelles Node-Verzeichnis + /opt/homebrew/bin + /usr/local/bin + Systemverzeichnisse) – ohne diesen Schritt stirbt der gespawnte App-Server bereits am Shebang.

macOS

App-Server im Hintergrund mit launchd

node scripts/install-launch-agent.mjs

Erstellt ~/Library/LaunchAgents/com.codex-mcp-bridge.app-server.plist (RunAtLoad + KeepAlive bei Absturz, ThrottleInterval 10s) und führt dann launchctl bootstrap gui/$UID aus. Der App-Server läuft bereits seit dem Login, daher muss die Bridge nicht selbst spawnen und Threads sind immer live.

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

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

Thread direkt in der Codex-Desktop-App ansehen

Die Codex-Desktop-App ist auf macOS /Applications/ChatGPT.app und registriert das Schema codex://. Die Bridge verwendet codex://threads/<threadId>, um den richtigen Thread zu öffnen:

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

So kann der Auftraggeber sehen, was Codex gerade tut, anstatt nach Abschluss das Rollout ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl erneut zu lesen.

Einschränkungen unter macOS

• Die Codex-Desktop-App startet ihren eigenen App-Server über stdio (ChatGPT.app/Contents/Resources/codex … app-server) und akzeptiert keinen externen Endpoint. Threads, die in der App geöffnet sind, lassen sich zwar über die Bridge ansprechen, jedoch über den Resume-Mechanismus aus der Rollout-Datei .jsonl, nicht als Live-Attach. Nicht in einen Thread senden, der gerade in der Desktop-App einen Turn ausführt – zwei App-Server, die dasselbe Rollout schreiben, können die Historie beschädigen. Vorher den status mit list_codex_threads prüfen und nur senden, wenn idle/notLoaded vorliegt.

• Ein Repository auf einer NTFS-Partition eines Dual-Boot-Rechners (/Volumes/...) ist unter macOS nur lesbar – macOS mountet NTFS schreibgeschützt. Behalte ein separates Checkout auf einem APFS-Laufwerk (z. B. ~/code/codex-mcp-bridge), um darin zu laufen und zu ändern.

• codex app-server daemon start verwendet den Transport unix:// mit dem Control-Socket ~/.codex/app-server-control/app-server-control.sock. Die Bridge nutzt diesen Weg nicht (das Frame-Protokoll unterscheidet sich von WebSocket, keine öffentliche API) – sie kommuniziert immer über ws://.

Umgebungsvariablen

Zur Genehmigung: Codex fragt nach der Freigabe von Befehlen/Patches, wenn approval_policy nicht never ist. Da niemand vor Claude Desktop sitzt, um zu klicken, antwortet die Bridge automatisch gemäß CODEX_BRIDGE_APPROVAL und protokolliert dies auf stderr. Der Standardwert approve passt zur Konfiguration approval_policy = "never" + sandbox_mode = "danger-full-access" in ~/.codex/config.toml. Wenn die Sandbox strenger eingestellt wird, sollte man auf deny wechseln.

Gemeinsame Nutzung des App-Servers mit einer interaktiven Codex-Sitzung

Öffne die TUI mit demselben Endpoint, damit der Thread in der TUI und der Bridge-Thread als derselbe erscheinen:

codex --remote ws://127.0.0.1:8791

App-Server manuell ausführen (unabhängig vom Bridge-Autostart):

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

Test

npm run check

Schnelltest: Bridge starten, App-Server bei Bedarf autostarten, Threads auflisten.

npm run smoke

Smoke-Test: Neuen Thread erstellen, zwei aufeinanderfolgende Turns senden und prüfen, ob sich Codex das Codewort aus dem vorherigen Turn merkt – das zeigt, dass der Thread wirklich kontinuierlich ist und nicht jedes Mal eine neue Sitzung erstellt wird.

Umgebung aus Claude heraus prüfen: Tool codex_bridge_status aufrufen.