Codex ↔ Claude Code / DeepSeek MCP Bridge

A local MCP server with two integration paths: Codex ↔ Claude Code, or Claude Desktop → Codex and Codex → the official DeepSeek API. CLI tasks launch fresh, non-interactive sessions. DeepSeek tasks create independent API consultations with no local tools.

This connects the agents through CLI and model API interfaces. It does not remote-control their windows, attach to an existing GUI chat, share hidden conversation history, or combine subscriptions. It is an independent community project.

Codex       → MCP bridge (--host codex)  → claude --print
Claude Code → MCP bridge (--host claude) → codex exec
Claude Desktop → MCP bridge (--host desktop) → codex exec
Codex → MCP bridge (--host codex --peer deepseek) → api.deepseek.com

Tasks return an ID immediately. Poll for a final result, or cancel the CLI process tree. Both installations can coexist. A shared workspace lock serializes bridge tasks, and an inherited child marker blocks recursive bridge delegation.

Claude Desktop and the official DeepSeek API

Claude Desktop and Claude Code are different hosts. Installing Desktop does not supply a claude --print executable or its authentication. For a Desktop + DeepSeek setup, Claude Code CLI and a separate gateway application are not required.

Desktop can connect to the Codex-facing MCP server using --host desktop (--host claude remains compatible). A Desktop configuration example and complete setup guide are included. The actual Desktop UI has not been exercised here.

For the reverse direction, select --peer deepseek in Codex and provide the bridge's API key environment variable and an explicit DeepSeek model ID. This calls only https://api.deepseek.com/chat/completions. It does not control Desktop or access its current conversation. Prompts/code context must be supplied explicitly; files are not uploaded automatically. No official DeepSeek model call has been completed without a locally available key. See v1.1 validation.

Related MCP server: claude_mcp

Install

Requirements: Node.js 22+, Git, and authenticated Codex CLI. The CLI-to-CLI path additionally needs authenticated Claude Code; the DeepSeek path needs an official API key and a selected model. Use a trusted local workspace. Calls consume the destination account's usage.

git clone https://github.com/Fahuikongjian/codex-claude-mcp-bridge.git
cd codex-claude-mcp-bridge
npm ci --ignore-scripts
node bin/bridge.mjs --help

Use absolute paths below. On Windows, forward slashes in the example paths work too. Use the absolute Node executable path if your app does not inherit your terminal's PATH. No npm registry publication is required.

Let Codex call the official DeepSeek API

Make DEEPSEEK_API_KEY and DEEPSEEK_MODEL available in the environment inherited by the bridge server. Select your actual model ID; no model is silently chosen. An example server-owner model configuration is included in examples/deepseek-config.json. Keep the key in the environment, not the config file or tool arguments.

codex mcp add deepseek_bridge -- node /absolute/path/codex-claude-mcp-bridge/bin/bridge.mjs serve --host codex --peer deepseek --workspace /absolute/path/your-project

Or print a Codex config snippet:

node bin/bridge.mjs config --host codex --peer deepseek --workspace /absolute/path/your-project

Call start_deepseek_task with a prompt, then poll get_task. The default output allowance is 2,048 tokens, adjustable from 1 to 8,192 through max_output_tokens. Thinking is disabled for bounded consultations. Only a normally completed text answer is a success; truncated answers, API errors, unexpected tool calls, and output overflow fail the task. The adapter does not execute tools or retry requests automatically.

The fixed endpoint and bearer authentication follow the official DeepSeek API guide. This provides a second opinion from DeepSeek; the Desktop application remains an independent MCP client.

Let Codex call Claude Code

codex mcp add claude_bridge -- node /absolute/path/codex-claude-mcp-bridge/bin/bridge.mjs serve --host codex --workspace /absolute/path/your-project

Alternatively, generate a snippet for your Codex config.toml:

node bin/bridge.mjs config --host codex --workspace /absolute/path/your-project

The generator prints configuration; it never changes host files. Merge its output into the appropriate Codex configuration. Restart the host or reload its MCP connections, then check codex mcp list. The official Codex MCP guide describes configuration scopes and tool policy.

Let Claude Code call Codex

claude mcp add --transport stdio codex_bridge -- node /absolute/path/codex-claude-mcp-bridge/bin/bridge.mjs serve --host claude --workspace /absolute/path/your-project

Or generate JSON and merge its mcpServers entry into your chosen Claude Code MCP configuration:

node bin/bridge.mjs config --host claude --workspace /absolute/path/your-project

Check claude mcp list or /mcp. Choose one registration method to avoid duplicate servers. See the official Claude Code MCP guide for project, local, and user scopes.

Optional Claude Code plugin wrapper

The repository includes .claude-plugin/plugin.json and .mcp.json. After running npm ci in the clone, load it locally:

claude --plugin-dir /absolute/path/codex-claude-mcp-bridge

This wrapper exposes the Codex direction and binds it to ${CLAUDE_PROJECT_DIR}. It requires Node and Codex on the host's PATH. Keep the installed clone's dependencies available. The plain MCP registration works with both hosts and supports custom executable paths; do not register the wrapper and plain Codex direction together.

Use

In Codex, ask:

Use start_claude_task to review src/parser.js for edge cases. Consult mode only. Do not change files. Poll get_task and summarize the findings with evidence.

In Claude Code, ask:

Use start_codex_task to independently check the test failure in this workspace. Do not change files. Poll get_task and report the cause and a proposed fix.

CLI task arguments:

{
  "prompt": "Review src/parser.js. Report reproducible issues and their file locations.",
  "cwd": ".",
  "mode": "consult",
  "timeout_seconds": 120,
  "max_turns": 8
}

model is optional and defaults to the destination CLI's configuration. cwd must resolve to a directory within the configured workspace, including after symlink resolution. Timeout is 1–600 seconds. Claude's turn limit is 1–30; Codex ignores max_turns and uses the wall-clock timeout. Prompt length is capped at 32,000 characters.

Use the returned id as get_task.task_id. Poll with wait_ms: 1000, with a brief pause between calls for long tasks. Terminal states are succeeded, failed, timed_out, and cancelled. A successful task returns result.text; Claude results also expose permission_denials, which the caller should inspect. CLI failure is a failed task, not an MCP protocol failure. Validation, policy, and unknown-ID errors use MCP isError.

DeepSeek tasks accept prompt, optional model, timeout_seconds, and max_output_tokens. Model selection uses the task argument, then deepseek.model in the owner config, then DEEPSEEK_MODEL. The key comes from DEEPSEEK_API_KEY by default, or the environment variable named by deepseek.api_key_env. There is no key or endpoint tool argument. API task results include the final text, model, endpoint, and numeric token usage when provided.

Edits

Default consult uses the Codex read-only sandbox, or Claude's plan mode with only Read,Glob,Grep. To permit delegated edits, the server owner must add --allow-edits to the launch command, and the caller must explicitly request mode: "edit".

Edit mode selects Codex's workspace-write sandbox, or Claude's acceptEdits mode with Read,Glob,Grep,Edit,Write. Claude's shell tools are deliberately absent; the calling agent can run validation after inspecting changes. The bridge does not pass either CLI's dangerous permission-bypass flags. Codex runs with approval_policy="never" so an unattended task cannot wait for interactive escalation; commands outside its sandbox are denied.

The Codex CLI reference and Claude Code CLI reference document the flags used by these adapters. Host approval of an MCP tool does not automatically approve operations inside the destination CLI.

Executable configuration

Native codex/claude executables on PATH are discovered automatically. Windows npm installations of the known CLI packages are resolved directly, including Claude's native bin/claude.exe and older cli.js layouts. Arbitrary .cmd/.bat launchers are rejected instead of being passed through a shell.

For other installations, supply a server-owner JSON file using --config /absolute/path/bridge.json:

{
  "codex": { "command": ["C:/tools/codex.exe"] },
  "claude": { "command": ["C:/tools/claude.exe"] }
}

For an older JavaScript CLI, use {"command":["C:/tools/node.exe","C:/path/to/cli.js"]}. Command arrays are administrator-controlled launch configuration, never tool arguments. Do not point them at untrusted scripts. Prompts are sent over stdin and child processes use shell: false.

Coordination and lifecycle

• The caller owns the acceptance criteria and the final decision. Give the worker a bounded task and owned files; review its evidence before accepting changes.

• Each child inherits CODEX_CLAUDE_BRIDGE_CHILD=1. Another copy of this bridge in that child refuses to launch further tasks. Claude children additionally use an empty, strict MCP configuration. This is a cooperative recursion guard, not a security boundary against a process deliberately clearing its environment.

• One task at a time is allowed for each canonical configured workspace across bridge processes, including both directions and consult tasks. Both registrations must use the same workspace root. Different roots and external editors/agents are not coordinated by this lock.

• A lock file is created atomically under the OS temp directory in codex-claude-mcp-bridge/. Normal completion, failure, cancellation, and connection shutdown release it. The lock remains if the server is forcibly killed. Find its path with bridge_status; inspect its PID and confirm that the previous server and its CLI children have stopped before manually removing that one stale file. No automatic stale-lock takeover is attempted.

• Tasks and results are held only in memory, limited to the latest 32 tasks. Codex uses ephemeral sessions; Claude disables session persistence. The bridge writes no prompt/result log. Destination CLIs can still maintain their own authentication, diagnostics, caches, hooks, and settings.

• Timeouts, cancellation, and normal MCP disconnection terminate the active process tree (taskkill /T /F on Windows; a process group on Unix). Forced server termination and commands that deliberately detach themselves require external process supervision. Cancellation does not roll back edits.

• CLI output is bounded to 1 MiB total; the final answer is bounded to 64 KiB. Exceeding either is a failed task. No result is silently truncated into success.

• DeepSeek tasks use the same workspace lock and task lifecycle. Cancellation aborts the local HTTP request; it cannot guarantee that the provider stops processing or billing. HTTP redirects are rejected. Responses are capped at 1 MiB and final text at 64 KiB. API error bodies are excluded, and the active credential is redacted from returned text. The adapter does not read Desktop settings or credentials.

The workspace check confines the launch directory, not every file the downstream CLI can read. Claude permissions are not an OS filesystem sandbox, and Codex may load local settings and hooks. The server inherits the account environment to preserve CLI authentication. Use a workspace, configuration, and executable you trust; the bridge adds no HTTP listener or credential store.

Verify

npm run check
npm test

The suite uses deterministic CLI fixtures and real MCP stdio clients. It requires no model credentials. A GitHub Actions matrix is configured for Windows, macOS, and Linux with Node 22/24; inspect the actual run before claiming platform coverage.

Optional model-backed smoke tests, after authenticating each destination CLI:

node scripts/smoke.mjs --provider codex --workspace /absolute/path/your-project
node scripts/smoke.mjs --provider claude --workspace /absolute/path/your-project
node scripts/smoke.mjs --provider deepseek --workspace /absolute/path/your-project

The smoke script accepts --config too. Current results and limits are recorded in the v1.1 test report. The v1.0 report is retained as historical evidence.

MIT licensed. Not affiliated with OpenAI or Anthropic.