Codex MCP Server

Codex MCP工具

Codex MCP Tool是一个开源的模型上下文协议（MCP）服务器，它将您的IDE或AI助手（Claude、Cursor等）连接到Codex CLI。它实现了非交互式自动化 codex exec、安全的沙盒编辑和批准，以及通过以下方式进行大规模代码分析 @ 文件引用。它专为可靠性和速度而构建，流式传输进度更新，支持结构化更改模式（旧/新补丁输出），并与标准MCP客户端干净集成，用于代码审查、重构、文档和CI自动化。

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

• 向您的MCP客户询问Codex问题，或以编程方式集思广益。

太长，读不下去了 +Codex CLI

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

先决条件

在使用此工具之前，请确保您已：

1. **** （v18.0.0或更高版本）
2. Codex CLI 已安装并验证

✅ 与跨平台支持：经过全面测试，可在Windows、macOS和Linux（v1.2.4+）上运行

单线设置

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

验证安装

类型 /mcp 在Claude Code内部验证Codex MCP是否处于活动状态。

______________________________________________________________________

替代方案：从Claude Desktop导入

如果您已经在Claude Desktop中配置了它：

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

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

1. 导入到克劳德代码：

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"
    }
  }
}

配置文件位置：

• 克劳德桌面:

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json - Linux: ~/.config/claude/claude_desktop_config.json

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

工作流示例

• 自然语言：“使用codex解释index.html”，“使用@src理解此仓库”，“查找漏洞并提出修复建议”
• 克劳德代码：类型 /codex-cli 访问MCP服务器工具。

使用示例

模型选择

// Use the default gpt-5-codex model
'explain the architecture of @src/';

// Use gpt-5 for fast general purpose reasoning
'use codex with model gpt-5 to analyze @config.json';

// Use o3 for deep reasoning tasks
'use codex with model o3 to analyze complex algorithm in @algorithm.py';

// Use o4-mini for quick tasks
'use codex with model o4-mini to add comments to @utils.js';

// Use codex-1 for software engineering
'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 CLI支持通过沙盒模式和批准策略对权限和批准进行细粒度控制。

了解参数

这 sandbox 参数（方便标志）：

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

粒度控制参数：

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

沙盒模式

审批政策

配置示例

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

{
  "approvalPolicy": "on-failure",
  "sandboxMode": "workspace-write",  // Auto-set if omitted in v1.2+
  "model": "gpt-5-codex",
  "prompt": "refactor @src/utils for better performance"
}

示例2：快速自动化（便利模式）

{
  "sandbox": true,  // Equivalent to fullAuto: 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+）

从1.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：验证沙盒模式

# Ensure you're not using read-only mode for write operations
{
  "sandboxMode": "workspace-write",  // Not "read-only"
  "approvalPolicy": "on-failure"
}

检查2：使用方便标志

# Let the server handle defaults
{
  "sandbox": true,  // Simple automation
  "prompt": "your task"
}

检查3：更新到最新版本

# v1.2+ includes smart defaults to prevent permission errors
npm install -g @cexll/codex-mcp-server@latest

常见问题

问题1:MCP工具超时错误

如果在使用Codex MCP工具时遇到超时错误：

# Set the MCP tool timeout environment variable (in milliseconds)
export MCP_TOOL_TIMEOUT=36000000  # 10 hours

# For Windows (PowerShell):
$env:MCP_TOOL_TIMEOUT=36000000

# For Windows (CMD):
set MCP_TOOL_TIMEOUT=36000000

将此添加到您的shell配置文件中(~/.bashrc, ~/.zshrc，或PowerShell配置文件）使其永久化。

问题2：Codex无法写入文件

如果Codex返回权限错误，如“操作被沙盒策略阻止”或“被用户批准设置拒绝”，请配置您的Codex CLI设置：

创建或编辑 ~/.codex/config.toml:

# Dynamically generated Codex configuration
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

⚠️ 安全警告：The danger-full-access 模式授予Codex完全文件系统访问权限。仅在受信任的环境和您完全理解的任务中使用此配置。

配置文件位置：

• macOS/Linux: ~/.codex/config.toml
• 视窗: %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检查会干扰自动化时出现权限错误。

高级示例

// Using ask-codex with specific model
'ask codex using gpt-5 to refactor @utils/database.js for better performance';

// Brainstorming with constraints
"brainstorm solutions for reducing API latency with constraints: 'must use existing infrastructure, budget under $5k'";

// Change mode for structured edits
'use codex in change mode to update all console.log to use winston logger in @src/';

工具（用于AI）

这些工具旨在供AI助手使用。

核心工具

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

- 支持 @ 用于包含文件内容的文件引用 - 可选的 model 参数-可用型号： - gpt-5-codex （默认，针对编码进行了优化） - gpt-5 （通用，快速推理） - o3 （最聪明、最深刻的推理） - o4-mini （快速高效） - codex-1 （基于o3的软件工程） - codex-mini-latest （低延迟代码问答） - gpt-4.1 （也可用） - sandbox=true 使能够 --full-auto 模式 - changeMode=true 返回结构化的旧/新编辑 - 支持审批策略和沙盒模式 - 自动包含 --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：从changeMode响应中检索缓存块。

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

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

- 在指定的持续时间内运行（毫秒） - 可用于测试长时间运行的操作

Slash命令（用户）

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

• /分析：使用Codex分析文件或目录，或提出一般性问题。

- prompt （必填）：分析提示。使用 @ 语法以包括文件（例如。， /analyze prompt:@src/ summarize this directory)或提出一般性问题（例如。， /analyze prompt:Please use a web search to find the latest news stories).

• /沙箱：使用Codex批准模式安全测试代码或脚本。

- prompt （必填）：代码测试请求（例如。， /sandbox prompt:Create and run a Python script that processes CSV data 或 /sandbox prompt:@script.py Test this script safely).

• /帮助：显示Codex CLI帮助信息。
• /ping：测试与服务器的连接。

- message （可选）：要回显的消息。

最近的更新

v1.2.4（2025-10-27）

🔧 主要改进：

• Windows兼容性增强：替换了Node.js原生 spawn() 符合行业标准 cross-spawn 包裹

- 根本原因：以前 shell: true 修复程序在某些Windows配置上仍然失败 - 解决方案：使用 cross-spawn （每周下载量超过5000万次，由Webpack/Jest使用）用于自动Windows .cmd 处理 - 优点： - Windows用户无需配置 - 自动处理 .cmd, .ps1，以及 .exe 扩展 - 兼容CMD和PowerShell环境 - \<5ms性能开销 - 依赖关系：已添加 cross-spawn@^7.0.6 和 @types/cross-spawn

🐛 Bug修复：

• 通过Windows特定的4步故障排除指南增强ENOENT错误诊断
• 添加了可选链接 stdout/stderr 在TypeScript严格模式下处理空值

📝 文档：

• 在文档中添加了全面的Windows疑难解答部分
• 已记录 spawn codex ENOENT 错误解决步骤

v1.2.3（2025-10-27）

🐛 Bug修复：

• Windows兼容性：修复了尽管安装正确，但在Windows上Codex CLI检测失败的问题

- 根本原因： spawn() 随着 shell: false 无法解决 .cmd Windows上的扩展 - 解决方案：启用shell模式以执行跨平台命令 - 影响：零性能影响（~10ms开销），使用数组形式参数维护安全性 - 通过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及更早版本

• 智能沙盒模式默认防止权限错误
• 用于故障排除的增强调试信息
• 自动 --skip-git-repo-check 非git环境的标志
• 具有功能标志的Web搜索集成
• 支持分页的结构化更改模式

平台支持

最低要求：

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

致谢

贡献

欢迎投稿！请通过GitHub提交pull请求或报告问题。

许可证

该项目根据MIT许可证获得许可。看 许可证 文件以获取详细信息。

免责声明： 这是一个非官方的第三方工具，不隶属于OpenAI，也不受其认可或赞助。