codex-mcp-bridge

Английская версия

MCP-сервер для Claude Desktop, чтобы отправлять prompt прямо в существующий thread Codex через общий app-server Codex. Работает на macOS, Windows и Linux.

Это не codex exec (создаёт новую сессию каждый раз). Bridge общается по JSON-RPC с настоящим app-server Codex, поэтому thread сохраняет историю, 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; если он ещё не жив, сам запускает detached (codex app-server --listen ws://127.0.0.1:8791), и этот app-server продолжает работать независимо после выхода bridge.

• Любой клиент, указывающий на тот же URL, использует один общий app-server → thread/resume с threadId переподключается к тому же запущенному thread, а не открывает новую сессию.

• Bridge держит ровно один WebSocket, один раз выполняет initialize и маршрутизирует уведомления по threadId, поэтому параллельные thread не перемешиваются.

Related MCP server: webgpt MCP

Tools

send_to_codex_thread принимает также timeoutSec (по умолчанию 240), cwd, model, effort и openInApp (macOS — открыть thread в приложении перед отправкой для просмотра в реальном времени). По истечении таймаута turn не отменяется — bridge возвращает всё, что уже получено, вместе с turnId; продолжить чтение можно через read_codex_thread, остановить — через interrupt_codex_turn.

Установка в Claude Desktop

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

Скрипт сам определяет platform, создаёт файл конфигурации, если его нет, делает резервную копию старого (*.bak-<дата>-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) запускает MCP-сервер с урезанным PATH, поэтому codex обычно отсутствует в PATH. Bridge ищет в порядке — CODEX_BIN → привычные места установки для платформы → PATH:

На macOS/Linux codex — это Node-скрипт с shebang #!/usr/bin/env node, поэтому bridge также заново прописывает PATH (текущая директория node + /opt/homebrew/bin + /usr/local/bin + системные каталоги) для дочернего процесса — без этого шага spawn app-server умирает прямо на shebang.

macOS

App-server в фоне через launchd

node scripts/install-launch-agent.mjs

Создайте ~/Library/LaunchAgents/com.codex-mcp-bridge.app-server.plist (RunAtLoad + KeepAlive при сбое, ThrottleInterval 10s), затем launchctl bootstrap gui/$UID. App-server уже работает с момента входа в систему, поэтому bridge не нужно запускать его самостоятельно, и thread всегда в состоянии 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ỡ

Логи: ~/Library/Logs/codex-mcp-bridge/app-server.{out,err}.log.

Просмотр thread напрямую в Codex desktop app

Codex desktop app на macOS — это /Applications/ChatGPT.app, и он регистрирует схему codex://. Bridge использует codex://threads/<threadId>, чтобы открыть нужный thread:

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

Это способ для постановщика задачи видеть, что Codex делает, вместо того чтобы перечитывать rollout ~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl после завершения.

Ограничения на macOS

• Codex desktop app сам запускает отдельный app-server через stdio (ChatGPT.app/Contents/Resources/codex … app-server) и не принимает внешний endpoint. Thread, открытый в приложении, по-прежнему можно отправлять через bridge, но по механизму resume из rollout .jsonl, а не как live-подключение. Не отправляйте в thread, в котором прямо сейчас выполняется turn в desktop app — два app-server, пишущих в один rollout, могут повредить историю. Сначала проверяйте status через list_codex_threads, отправляйте только при idle/notLoaded.

• Репозиторий на NTFS-разделе машины с двойной загрузкой (/Volumes/...) на macOS доступен только для чтения — macOS монтирует NTFS read-only. Держите отдельный checkout на APFS-диске (например, ~/code/codex-mcp-bridge) для запуска и правок.

• codex app-server daemon start использует transport unix:// с control socket ~/.codex/app-server-control/app-server-control.sock. Bridge не использует этот путь (протокол кадрирования отличается от WebSocket, публичного API нет) — всегда общается через ws://.

Env

Об одобрении: Codex запрашивает подтверждение команд/патчей, если approval_policy не равен never. Рядом с Claude Desktop никого нет, чтобы нажимать кнопки, поэтому bridge отвечает сам согласно CODEX_BRIDGE_APPROVAL и пишет в stderr. Значение по умолчанию approve соответствует конфигурации approval_policy = "never" + sandbox_mode = "danger-full-access" в ~/.codex/config.toml; если вы ужесточаете sandbox, стоит сменить на deny.

Общий app-server с интерактивной сессией Codex

Откройте TUI, указывающий на тот же endpoint, чтобы thread в TUI и thread bridge были видны как один:

codex --remote ws://127.0.0.1:8791

Запустите app-server вручную (не полагаясь на автозапуск bridge):

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

Тест

npm run check

Быстрая проверка: bridge запускается, при необходимости autostart app-server, перечисляет thread.

npm run smoke

Smoke test создаёт новый thread, отправляет 2 подряд turn и проверяет, что Codex помнит кодовое слово из предыдущего turn — это значит, thread действительно непрерывный, а не новая сессия каждый раз.

Проверьте окружение из Claude: вызовите tool codex_bridge_status.