Claude–Codex MCP Bridge

让 Codex 通过 MCP 调用本机 Claude Code：Codex 发出任务，桥接器运行 claude -p，等待执行完成后返回结果和会话 ID，可继续同一会话。

默认通过 DeepSeek 的 Anthropic 兼容接口运行 Claude Code；CLAUDE_BRIDGE_BASE_URL 可指向其他兼容端点。

Codex → MCP stdio → server.js → Claude Code → DeepSeek
Codex ← 执行结果、会话 ID、费用和轮次 ← Claude Code

安装

需要 Node.js 18+、npm，以及已安装并完成配置的 Claude Code 和 Codex。Linux/macOS 已验证；Windows 使用 .cmd 包装器时需要确认 Codex 的启动环境能直接执行它。

git clone https://github.com/guiarch3-pixe/claude-codex-bridge.git
cd claude-codex-bridge
npm ci

Related MCP server: cursor-agent-bridge

配置（Linux / macOS）

将 DeepSeek API key 设置为启动 Codex 时可用的 DEEPSEEK_API_KEY 环境变量，或将密钥单独保存在 ${XDG_CONFIG_HOME:-$HOME/.config}/claude-codex-bridge/deepseek-api-key 文件中，并限制该文件仅自己可读写。启动示例会优先使用环境变量，再读取该文件。

在 ~/.codex/config.toml 添加以下内容，将所有示例绝对路径替换为自己的路径。如果已有 claude_code 配置，更新已有条目，避免重复表名。

[mcp_servers.claude_code]
command = "bash"
args = ["/absolute/path/to/claude-codex-bridge/start-bridge.example.sh"]
env_vars = ["DEEPSEEK_API_KEY"]
tool_timeout_sec = 1860

[mcp_servers.claude_code.env]
CLAUDE_BRIDGE_PROJECT_DIR = "/absolute/path/to/your/project"
CLAUDE_BRIDGE_CLAUDE_BIN = "/absolute/path/to/claude"

bash、node 必须能在 Codex 的启动环境中找到；使用 nvm 等工具时，请确认启动环境包含对应的 PATH。command 也可以使用 Bash 的绝对路径。

MCP 的配置字段见 Codex 官方 MCP 文档。配置后重启 Codex，可通过 codex mcp list 检查注册情况。

Windows 上可直接让 command 指向 node、args 指向 server.js，并在 [mcp_servers.claude_code.env] 设置目录和可执行文件；start-bridge.example.sh 需要 Git Bash 运行。DEEPSEEK_API_KEY 建议由父进程环境变量传入。

工具

桥接器提供 claude_run：

结果以 MCP 文本内容中的 JSON 返回，包含 ok、exit_code、session_id、result_text、total_cost_usd、num_turns 和 native_transcript_path（找不到转录文件时为 null）；错误时会返回错误说明，部分错误包含输出尾部。

环境变量

安全边界

• 桥接器只通过 stdio 与 MCP 客户端通信，不监听网络端口。只把它接到你信任的 Codex/MCP 客户端。

• Claude Code 会在 cwd 中读写文件并可能运行命令。默认权限模式是 acceptEdits；处理不可信仓库时，请降低权限、限制 allowed_tools，或放进容器/沙箱。

• INSTRUCTIONS 要求调用方在委派前检查工作区、执行后自行复核 diff，并且只做本地 commit、不自动 push。它是指令，不是强制隔离。

• 密钥只放在环境变量或权限为 0600 的 key 文件中；start-bridge.sh、密钥、会话文件和 node_modules/ 都不在版本库里。

测试

npm test

测试使用一个假的 claude 可执行文件和一个 MCP 客户端，验证参数拼装、输出解析、超时、转录路径和 claude_run 的完整 stdio 往返；不需要 API key 或网络。

已知限制

• native_transcript_path 是尽力而为：先按 Claude Code 的项目目录编码猜测，再按 session id 搜索 ~/.claude/projects；找不到时返回 null。转录文件由 Claude Code 自己维护。

• Windows 的 .cmd 启动未在自动化测试中验证；如遇 spawn 错误，请把 CLAUDE_BRIDGE_CLAUDE_BIN 指向可直接执行的文件。

• 测试不调用真实 Claude Code 或 DeepSeek，真实端到端执行需要你自己配置密钥后验证。

• 桥接器不做提示词注入防护、沙箱或权限提升；安全边界由 MCP 客户端、Claude Code 权限模式和运行环境共同决定。

License

MIT