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：⚠️ 繞過所有安全檢查（危險，不推薦）

沙盒模式

審批策略

配置示例

示例 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 標誌。
• 通過功能標誌集成了網絡搜索。
• 支持分頁的結構化變更模式。

平臺支持

最低要求：

• Node.js v18.0.0 或更高版本
• 已安裝並認證的 Codex CLI (npm install -g @openai/codex)

致謝

本項目受到了 jamubc/gemini-mcp-tool 的優秀工作的啟發。特別感謝 @jamubc 提供的原始 MCP 服務器架構和實現模式。

貢獻

歡迎貢獻代碼！請通過 GitHub 提交拉取請求或報告問題。

📄 許可證

本項目採用 MIT 許可證。有關詳細信息，請參閱 LICENSE 文件。

免責聲明：這是一個非官方的第三方工具，與 OpenAI 沒有關聯、未得到其認可或贊助。