Claude Code Codex MCP (claude-code-codex-mcp)

让 Claude Code 与 Codex 终极合体！
在 Claude Code 终端中直接调用 Codex 的历史会话（Sessions）、挂载后台任务，并自由使用 Codex 中配置的全部高性能大模型。

English Documentation | 中文说明文档

💡 为什么需要这个项目？

在现代 AI 辅助研发中，很多开发者同时使用两款顶尖工具：

1. Claude Code：Anthropic 官方强大的终端代码自主 Agent。

2. Codex (Desktop & CLI)：支持多元模型底座（如 Gemini 3.8 Flash、DeepSeek Flash、GPT-6、Grok 等）并拥有独立的会话记忆体系与沙箱执行环境。

之前两者是相互割裂的。本 MCP 服务打破了这个壁垒，将 Codex 的核心会话引擎与模型目录暴露为标准 MCP 工具，让 Claude Code 可以：

• 模型任意借力：随时调用 Codex 中的不同模型进行“双盲会诊”或专项复杂推理。

• 跨端会话缝合：你在 Codex 桌面版（GUI）里推进了一半的工作，在 Claude Code 里可以直接接着干，无需反复复制 Prompt 与代码。

• 主从分工协作：Claude Code 作为主脑负责整体架构与交互，把脏活累活丢给 Codex 作为后台 Worker 独立执行并保留历史痕迹。

架构流程图 (Architecture)

┌────────────────────────────────────────────────────────┐
│                      User Terminal                     │
│                            │                           │
│                      Claude Code                       │
│             (Main Reasoning / Interaction)             │
└────────────────────────────┬───────────────────────────┘
                             │
                  Standard MCP (Stdio)
                             │
┌────────────────────────────▼───────────────────────────┐
│               claude-code-codex-mcp                    │
│   (Session Scanner | Model Catalog | Exec Engine)      │
└──────────────┬───────────────────────────┬─────────────┘
               │                           │
        Inspect / Read              Spawn & Stream
               │                           │
┌──────────────▼─────────────┐   ┌─────────▼─────────────┐
│  ~/.codex/session_index    │   │      codex exec       │
│  ~/.codex/sessions/*.jsonl │   │   -m <target_model>   │
│  ~/.codex/config.toml      │   │   resume / fork / run │
└────────────────────────────┘   └───────────────────────┘

🛠️ 提供的 8 大核心工具

🚀 快速上手 (Quick Start)

1. 安装与一键配置

克隆仓库后，运行对应的安装脚本即可自动安装依赖、执行自检并注册到 Claude Code：

Windows (PowerShell):

git clone https://github.com/your-username/claude-code-codex-mcp.git
cd claude-code-codex-mcp
.\install.ps1

Linux / macOS (Bash):

git clone https://github.com/your-username/claude-code-codex-mcp.git
cd claude-code-codex-mcp
chmod +x install.sh
./install.sh

2. 手动注册方式

如果你想手动注册到 Claude Code：

npm install
npm test
claude mcp add -s user codex node /path/to/claude-code-codex-mcp/src/index.mjs

检查注册状态：

claude mcp list

当看到 codex: node ... - √ Connected 即代表一切就绪！

💬 在 Claude Code 中的使用范例

在终端启动 claude 后，直接使用自然语言：

1. 多模型双盲评审：

   “请调用 codex_ask_model，使用 gemini-3.8-flash-high 模型审查当前目录下的认证逻辑是否存在漏洞。”

2. 跨端接力编程：

   “列出我刚才在 Codex 桌面端运行的会话，找到关于重构的那个会话 ID，并读取它的最新几轮对话。” “调用 codex_resume_session 继续该会话，换成 deepseek-flash 模型，让它补充单元测试。”

3. 后台异步工兵：

   “调用 codex_run_task 启动一个任务，把项目中的旧版 SDK 替换为新规范，完成后把 Session ID 汇报给我。”

💡 Why this project?

Developers often switch between Claude Code (Anthropic's autonomous terminal coding agent) and Codex (an agent with flexible model support such as Gemini 3.8 Flash, DeepSeek Flash, GPT-6, Grok, etc.).

claude-code-codex-mcp acts as a unified Model Context Protocol (MCP) bridge, enabling Claude Code to:

• Switch & Query Codex Models: Access external reasoning models directly within Claude Code.

• Unified Session Lifecycle: Read, resume, and fork Codex Desktop & CLI sessions seamlessly.

• Agent-to-Agent Delegation: Delegate complex tasks from Claude Code to Codex as a persistent background worker.

🚀 Installation

git clone https://github.com/your-username/claude-code-codex-mcp.git
cd claude-code-codex-mcp
npm install
npm test

Register to Claude Code:

claude mcp add -s user codex node "$(pwd)/src/index.mjs"

Verify connection:

claude mcp list
# Output: codex: node ... - √ Connected

📄 License

MIT License. See LICENSE for details.