⚙

模型上下文协议服务器

Codex MCP Tool是一个开源的模型上下文协议（MCP）服务器，用于连接IDE或AI助手（如Claude、Cursor等）与Codex CLI，支持非交互式自动化、安全沙箱编辑和大规模代码分析。

作者 By cexll
本地部署 代码分析 自动化工具
GitHub

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 Tool MCP server

太长，读不下去了 +Codex CLI

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

先决条件

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

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

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

单线设置

BASH``` 1claude mcp add codex-cli — npx -y @cexll/codex-mcp-server


### 验证安装


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



---


### 替代方案：从Claude Desktop导入


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


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


JSON```
1
2
3
4"codex-cli": {
  "command": "npx",
  "args": ["-y", "@cexll/codex-mcp-server"]
}
  1. 导入到克劳德代码：

BASH``` 1claude mcp add-from-claude-desktop


## 配置


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


### NPX使用（推荐）


将此配置添加到您的Claude Desktop配置文件中：


JSON```
1
2
3
4
5
6
7
8{
  "mcpServers": {
    "codex-cli": {
      "command": "npx",
      "args": ["-y", "@cexll/codex-mcp-server"]
    }
  }
}

全球安装

如果全局安装，请改用此配置：

JSON``` 1 2 3 4 5 6 7{ “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服务器工具。


## 使用示例


### 模型选择


JAVASCRIPT```
1
2
3
4
5
6
7
8
9
10// 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: ⚠️ 绕过所有安全检查（危险，不建议）

沙盒模式

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

审批政策

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

配置示例

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

JAVASCRIPT``` 1 2 3 4 5 6{ “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：快速自动化（便利模式）**


JAVASCRIPT```
1
2
3
4
5{
  "sandbox": true,  // Equivalent to fullAuto: true
  "model": "gpt-5-codex",
  "prompt": "fix type errors in @src/"
}

示例3：只读分析

JAVASCRIPT``` 1 2 3 4 5{ “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：验证沙盒模式**


BASH```
1
2
3
4
5# Ensure you're not using read-only mode for write operations
{
  "sandboxMode": "workspace-write",  // Not "read-only"
  "approvalPolicy": "on-failure"
}

检查2：使用方便标志

BASH``` 1 2 3 4 5# Let the server handle defaults { “sandbox”: true, // Simple automation “prompt”: “your task” }


**检查3：更新到最新版本**


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

常见问题

问题1:MCP工具超时错误

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

BASH``` 1 2 3 4 5 6# 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`:


TOML```
1
2
3
4
5
6
7
8# 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检查会干扰自动化时出现权限错误。

高级示例

JAVASCRIPT``` 1 2 3 4 5 6// 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搜索集成
- 支持分页的结构化更改模式


## 平台支持


| 平台 | 状态 | 注释 |
| --- | --- | --- |
| **视窗** | ✅ 完全支持 | 在v1.2.4中通过交叉生成进行了增强 |
| **macOS** | ✅ 完全支持 | 在Darwin 23.5.0+上测试 |
| **Linux** | ✅ 完全支持 | 在Ubuntu最新版本上测试 |


**最低要求：**


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


## 致谢


这个项目的灵感来自于 [jamubc/gemini mcp工具](https://github.com/jamubc/gemini-mcp-tool)特别感谢 [@jamubc](https://github.com/jamubc) 对于原始的MCP服务器架构和实现模式。


## 贡献


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


## 许可证


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


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