Codex MCP Server

🚀 Codex MCP Tool

Codex MCP Tool 是一个开源的模型上下文协议（MCP）服务器，它能将你的 IDE 或 AI 助手（如 Claude、Cursor 等）连接到 Codex CLI。借助该工具，你可以使用 codex exec 实现非交互式自动化操作，通过审批进行安全的沙盒编辑，并通过 @ 文件引用进行大规模代码分析。它具备可靠性和高速度，能流式传输进度更新，支持结构化变更模式（OLD/NEW 补丁输出），并能与标准 MCP 客户端完美集成，用于代码审查、重构、文档编写和 CI 自动化。

最新版本 (v1.2.4)：增强了 Windows 兼容性 - 现在使用 cross-spawn 以在所有平台（Windows、macOS、Linux）上可靠地执行 npm 全局命令。查看更新日志

• 你可以从 MCP 客户端向 Codex 提问，或通过编程方式进行头脑风暴。

🚀 快速开始

目标：直接从支持 MCP 的编辑器中使用 Codex 高效地分析和编辑代码。

✨ 主要特性

• 连接 IDE 或 AI 助手与 Codex CLI。
• 支持非交互式自动化操作、安全沙盒编辑和大规模代码分析。
• 流式传输进度更新，支持结构化变更模式。
• 与标准 MCP 客户端完美集成。

📦 安装指南

前提条件

在使用此工具之前，请确保你已具备以下条件：

1. Node.js（v18.0.0 或更高版本）
2. 已安装并认证 Codex CLI

✅ 跨平台支持：在 Windows、macOS 和 Linux（v1.2.4+）上经过全面测试并正常工作。

一键设置

claude mcp add codex-cli -- npx -y @cexll/codex-mcp-server

验证安装

在 Claude Code 中输入 /mcp 以验证 Codex MCP 是否处于活动状态。

替代方法：从 Claude Desktop 导入

如果你已在 Claude Desktop 中进行了配置，请按以下步骤操作：

1. 添加到你的 Claude Desktop 配置中：

"codex-cli": {
  "command": "npx",
  "args": ["-y", "@cexll/codex-mcp-server"]
}

2. 导入到 Claude Code：

claude mcp add-from-claude-desktop

⚙️ 配置

在 MCP 客户端中注册 MCP 服务器：

推荐使用 NPX

将以下配置添加到你的 Claude Desktop 配置文件中：

{
  "mcpServers": {
    "codex-cli": {
      "command": "npx",
      "args": ["-y", "@cexll/codex-mcp-server"]
    }
  }
}

全局安装

如果你进行了全局安装，请使用以下配置：

{
  "mcpServers": {
    "codex-cli": {
      "command": "codex-mcp"
    }
  }
}

配置文件位置：

• Claude Desktop：
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json
  • Linux：~/.config/claude/claude_desktop_config.json

更新配置后，请重新启动终端会话。

💻 使用示例

基础用法

模型选择

// 使用默认的 gpt-5-codex 模型
'explain the architecture of @src/';

// 使用 gpt-5 进行快速通用推理
'use codex with model gpt-5 to analyze @config.json';

// 使用 o3 进行深度推理任务
'use codex with model o3 to analyze complex algorithm in @algorithm.py';

// 使用 o4-mini 进行快速任务
'use codex with model o4-mini to add comments to @utils.js';

// 使用 codex-1 进行软件工程
'use codex with model codex-1 to refactor @legacy-code.js';

使用文件引用（使用 @ 语法）

• ask codex to analyze @src/main.ts and explain what it does
• use codex to summarize @. the current directory
• analyze @package.json and list dependencies

通用问题（不使用文件）

• ask codex to explain div centering
• ask codex about best practices for React development related to @src/components/Button.tsx

头脑风暴与构思

• brainstorm ways to optimize our CI/CD pipeline using SCAMPER method
• use codex to brainstorm 10 innovative features for our app with feasibility analysis
• ask codex to generate product ideas for the healthcare domain with design-thinking approach

高级用法

Codex 审批与沙盒

Codex CLI 通过沙盒模式和审批策略支持对权限和审批进行细粒度控制。

理解参数

sandbox 参数（便捷标志）：

• sandbox: true → 启用 fullAuto 模式（相当于 fullAuto: true）
• sandbox: false（默认） → 不会禁用沙盒，只是不启用自动模式
• 重要提示：sandbox 参数是一个便捷标志，而非安全控制。

细粒度控制参数：

• sandboxMode：控制文件系统访问级别
• approvalPolicy：控制何时需要用户审批
• fullAuto：sandboxMode: "workspace-write" + approvalPolicy: "on-failure" 的简写
• yolo：⚠️ 绕过所有安全检查（危险，不推荐）

沙盒模式

模式	描述	使用场景
read-only	仅进行分析，不修改文件	代码审查、探索、文档阅读
workspace-write	可以修改工作区中的文件	大多数开发任务、重构、修复 bug
danger-full-access	包括网络在内的完全系统访问权限	高级自动化、CI/CD 管道

审批策略

策略	描述	使用场景
never	无需审批	完全受信任的自动化操作
on-request	每次操作前询问用户	最大程度的控制，手动审查
on-failure	仅在操作失败时询问用户	平衡的自动化操作（推荐）
untrusted	最高级别的安全模式	不信任的代码或高风险更改

配置示例

示例 1：平衡的自动化操作（推荐）

{
  "approvalPolicy": "on-failure",
  "sandboxMode": "workspace-write",  // 在 v1.2+ 版本中，如果省略则自动设置
  "model": "gpt-5-codex",
  "prompt": "refactor @src/utils for better performance"
}

示例 2：快速自动化操作（便捷模式）

{
  "sandbox": true,  // 简单自动化操作
  "model": "gpt-5-codex",
  "prompt": "fix type errors in @src/"
}

示例 3：只读分析

{
  "sandboxMode": "read-only",
  "model": "gpt-5-codex",
  "prompt": "analyze @src/ and explain the architecture"
}

智能默认设置（v1.2+）

从 v1.2.0 版本开始，服务器会自动应用智能默认设置以防止权限错误：

• ✅ 如果设置了 approvalPolicy 但未设置 sandboxMode → 自动设置 sandboxMode: "workspace-write"
• ✅ 如果 search: true 或 oss: true → 自动设置 sandboxMode: "workspace-write"（用于网络访问）
• ✅ 所有命令都包含 --skip-git-repo-check 以防止在非 git 环境中出现错误

解决权限错误

如果你遇到 ❌ Permission Error: Operation blocked by sandbox policy 错误，请按以下步骤检查： 检查 1：验证 sandboxMode

# 确保你没有在写操作中使用只读模式
{
  "sandboxMode": "workspace-write",  // 不是 "read-only"
  "approvalPolicy": "on-failure"
}

检查 2：使用便捷标志

# 让服务器处理默认设置
{
  "sandbox": true,  // 简单自动化操作
  "prompt": "your task"
}

检查 3：更新到最新版本

# v1.2+ 版本包含智能默认设置以防止权限错误
npm install -g @cexll/codex-mcp-server@latest

常见问题

问题 1：MCP 工具超时错误 如果你在使用 Codex MCP 工具时遇到超时错误，请按以下步骤操作：

# 设置 MCP 工具超时环境变量（以毫秒为单位）
export MCP_TOOL_TIMEOUT=36000000  # 10 小时

# 对于 Windows（PowerShell）：
$env:MCP_TOOL_TIMEOUT=36000000

# 对于 Windows（CMD）：
set MCP_TOOL_TIMEOUT=36000000

将上述命令添加到你的 shell 配置文件（~/.bashrc、~/.zshrc 或 PowerShell 配置文件）中，以使设置永久生效。

问题 2：Codex 无法写入文件 如果 Codex 响应权限错误，如 "Operation blocked by sandbox policy" 或 "rejected by user approval settings"，请配置你的 Codex CLI 设置： 创建或编辑 ~/.codex/config.toml：

# 动态生成的 Codex 配置
model = "gpt-5-codex"
model_reasoning_effort = "high"
model_reasoning_summary = "detailed"
approval_policy = "never"
sandbox_mode = "danger-full-access"
disable_response_storage = true
network_access = true

⚠️ 安全警告：danger-full-access 模式会授予 Codex 完全的文件系统访问权限。请仅在受信任的环境中使用此配置，并确保你完全理解相关任务。

配置文件位置：

• macOS/Linux：~/.codex/config.toml
• Windows：%USERPROFILE%\.codex\config.toml

更新配置后，请重新启动 MCP 客户端（Claude Desktop、Claude Code 等）。

基本示例

• use codex to create and run a Python script that processes data
• ask codex to safely test @script.py and explain what it does

默认行为：

• 所有 codex exec 命令都会自动包含 --skip-git-repo-check 以避免不必要的 git 仓库检查，因为并非所有执行环境都是 git 仓库。
• 这可以防止在非 git 目录中运行 Codex 或 git 检查会干扰自动化时出现权限错误。

高级示例

// 使用特定模型向 Codex 提问
'ask codex using gpt-5 to refactor @utils/database.js for better performance';

// 带约束条件的头脑风暴
"brainstorm solutions for reducing API latency with constraints: 'must use existing infrastructure, budget under $5k'";

// 结构化编辑的变更模式
'use codex in change mode to update all console.log to use winston logger in @src/';

工具（供 AI 使用）

这些工具是为 AI 助手设计的。

核心工具

• ask-codex：通过 codex exec 向 Codex 发送提示。

  • 支持 @ 文件引用以包含文件内容
  • 可选的 model 参数 - 可用模型：
    • gpt-5-codex（默认，针对编码进行了优化）
    • gpt-5（通用，快速推理）
    • o3（最智能，深度推理）
    • o4-mini（快速高效）
    • codex-1（基于 o3 的软件工程模型）
    • codex-mini-latest（低延迟代码问答）
    • gpt-4.1（也可用）
  • sandbox=true 启用 --full-auto 模式
  • changeMode=true 返回结构化的 OLD/NEW 编辑
  • 支持审批策略和沙盒模式
  • 自动包含 --skip-git-repo-check 以防止在非 git 环境中出现权限错误

• brainstorm：使用结构化方法生成新颖的想法。

  • 多种框架：发散、收敛、SCAMPER、设计思维、横向思维
  • 特定领域的上下文（软件、业务、创意、研究、产品、营销）
  • 支持与 ask-codex 相同的模型（默认：gpt-5-codex）
  • 可配置的想法数量和分析深度
  • 包括可行性、影响和创新性评分
  • 示例：brainstorm prompt:"ways to improve code review process" domain:"software" methodology:"scamper"

• ping：一个简单的测试工具，用于回显消息。

  • 用于验证 MCP 连接是否正常工作
  • 示例：/codex-cli:ping (MCP) "Hello from Codex MCP!"

• help：显示 Codex CLI 帮助文本和可用命令。

高级工具

• fetch-chunk：从变更模式响应中检索缓存的块。

  • 用于对大型结构化编辑响应进行分页
  • 需要 cacheKey 和 chunkIndex 参数

• timeout-test：用于防止超时的测试工具。

  • 运行指定的毫秒数
  • 用于测试长时间运行的操作

斜杠命令（供用户使用）

你可以在 Claude Code 的界面中直接使用这些命令（与其他客户端的兼容性尚未测试）。

• /analyze：使用 Codex 分析文件或目录，或提出通用问题。
  • prompt（必需）：分析提示。使用 @ 语法包含文件（例如，/analyze prompt:@src/ summarize this directory）或提出通用问题（例如，/analyze prompt:Please use a web search to find the latest news stories）。
• /sandbox：使用 Codex 审批模式安全地测试代码或脚本。
  • prompt（必需）：代码测试请求（例如，/sandbox prompt:Create and run a Python script that processes CSV data 或 /sandbox prompt:@script.py Test this script safely）。
• /help：显示 Codex CLI 帮助信息。
• /ping：测试与服务器的连接。
  • message（可选）：要回显的消息。

📚 详细文档

近期更新

v1.2.4 (2025-10-27)

🔧 重大改进：

• 增强 Windows 兼容性：用行业标准的 cross-spawn 包取代了 Node.js 原生的 spawn()。
  • 根本原因：之前的 shell: true 修复在某些 Windows 配置上仍然失败。
  • 解决方案：使用 cross-spawn（每周下载量超过 5000 万次，被 Webpack/Jest 使用）自动处理 Windows .cmd 文件。
  • 优点：
    • Windows 用户无需进行任何配置。
    • 自动处理 .cmd、.ps1 和 .exe 扩展名。
    • 与 CMD 和 PowerShell 环境兼容。
    • 性能开销小于 5 毫秒。
  • 依赖项：添加了 cross-spawn@^7.0.6 和 @types/cross-spawn。

🐛 错误修复：

• 增强了 ENOENT 错误诊断，并提供了针对 Windows 的 4 步故障排除指南。
• 在 TypeScript 严格模式下添加了对 stdout/stderr 的可选链处理以处理空值。

📝 文档更新：

• 在文档中添加了全面的 Windows 故障排除部分。
• 记录了 spawn codex ENOENT 错误的解决步骤。

v1.2.3 (2025-10-27)

🐛 错误修复：

• Windows 兼容性：修复了尽管已正确安装但 Codex CLI 在 Windows 上检测失败的问题。
  • 根本原因：spawn() 且 shell: false 无法解析 Windows 上的 .cmd 扩展名。
  • 解决方案：启用 shell 模式以实现跨平台命令执行。
  • 影响：零性能影响（约 10 毫秒开销），使用数组形式的参数保持安全性。
  • 验证平台：通过 GitHub Actions CI 在 Windows、macOS 和 Linux 上进行了验证。

📝 文档更新：

• 将所有包引用从 @trishchuk/codex-mcp-tool 更新为 @cexll/codex-mcp-server。
• 增强了跨平台设置说明。

🔍 测试：

• CI/CD 现在在 Ubuntu、macOS 和 Windows 上对 Node.js 18.x、20.x 和 22.x 进行验证。

v1.2.2 及更早版本

• 智能沙盒模式默认设置以防止权限错误。
• 增强了调试信息以方便故障排除。
• 为非 git 环境自动添加 --skip-git-repo-check 标志。
• 通过功能标志集成了网络搜索。
• 支持分页的结构化变更模式。

平台支持

平台	状态	备注
Windows	✅ 完全支持	在 v1.2.4 中通过 cross-spawn 增强
macOS	✅ 完全支持	在 Darwin 23.5.0+ 上进行了测试
Linux	✅ 完全支持	在 Ubuntu 最新版本上进行了测试

最低要求：

• Node.js v18.0.0 或更高版本
• 已安装并认证的 Codex CLI (npm install -g @openai/codex)

致谢

本项目受到了 jamubc/gemini-mcp-tool 的优秀工作的启发。特别感谢 @jamubc 提供的原始 MCP 服务器架构和实现模式。

贡献

欢迎贡献代码！请通过 GitHub 提交拉取请求或报告问题。

📄 许可证

本项目采用 MIT 许可证。有关详细信息，请参阅 LICENSE 文件。

免责声明：这是一个非官方的第三方工具，与 OpenAI 没有关联、未得到其认可或赞助。