Codex MCP Server

# Codex MCP Tool <div align="center"> [](https://github.com/x51xxx/codex-mcp-tool/releases) [](https://www.npmjs.com/package/@cexll/codex-mcp-server) [](https://www.npmjs.com/package/@cexll/codex-mcp-server) [](https://opensource.org/licenses/MIT) [](https://github.com/x51xxx/codex-mcp-tool) </div> Codex MCP Tool is an open‑source Model Context Protocol (MCP) server that connects your IDE or AI assistant (Claude, Cursor, etc.) to the Codex CLI. It enables non‑interactive automation with `codex exec`, safe sandboxed edits with approvals, and large‑scale code analysis via `@` file references. Built for reliability and speed, it streams progress updates, supports structured change mode (OLD/NEW patch output), and integrates cleanly with standard MCP clients for code review, refactoring, documentation, and CI automation. > **Latest Release (v1.2.4)**: Enhanced Windows compatibility - Now using cross-spawn for reliable npm global command execution across all platforms (Windows, macOS, Linux). [See changelog](#recent-updates) - Ask Codex questions from your MCP client, or brainstorm ideas programmatically. <a href="https://glama.ai/mcp/servers/@cexll/codex-mcp-server"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@cexll/codex-mcp-server/badge" alt="Codex Tool MCP server" /> </a> ## TLDR: [](#) + Codex CLI Goal: Use Codex directly from your MCP-enabled editor to analyze and edit code efficiently. ## Prerequisites Before using this tool, ensure you have: 1. **[Node.js](https://nodejs.org/)** (v18.0.0 or higher) 2. **[Codex CLI](https://github.com/openai/codex)** installed and authenticated > **✅ Cross-Platform Support**: Fully tested and working on Windows, macOS, and Linux (v1.2.4+) ### One-Line Setup ```bash claude mcp add codex-cli -- npx -y @cexll/codex-mcp-server ``` ### Verify Installation Type `/mcp` inside Claude Code to verify the Codex MCP is active. --- ### Alternative: Import from Claude Desktop If you already have it configured in Claude Desktop: 1. Add to your Claude Desktop config: ```json "codex-cli": { "command": "npx", "args": ["-y", "@cexll/codex-mcp-server"] } ``` 2. Import to Claude Code: ```bash claude mcp add-from-claude-desktop ``` ## Configuration Register the MCP server with your MCP client: ### For NPX Usage (Recommended) Add this configuration to your Claude Desktop config file: ```json { "mcpServers": { "codex-cli": { "command": "npx", "args": ["-y", "@cexll/codex-mcp-server"] } } } ``` ### For Global Installation If you installed globally, use this configuration instead: ```json { "mcpServers": { "codex-cli": { "command": "codex-mcp" } } } ``` **Configuration File Locations:** - **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` After updating the configuration, restart your terminal session. ## Example Workflow - Natural language: "use codex to explain index.html", "understand this repo with @src", "look for vulnerabilities and suggest fixes" - Claude Code: Type `/codex-cli` to access the MCP server tools. ## Usage Examples ### Model Selection ```javascript // 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'; ``` ### With File References (using @ syntax) - `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` ### General Questions (without files) - `ask codex to explain div centering` - `ask codex about best practices for React development related to @src/components/Button.tsx` ### Brainstorming & Ideation - `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 Approvals & Sandbox Codex CLI supports fine-grained control over permissions and approvals through sandbox modes and approval policies. #### Understanding Parameters **The `sandbox` Parameter (Convenience Flag):** - `sandbox: true` → Enables **fullAuto** mode (equivalent to `fullAuto: true`) - `sandbox: false` (default) → Does **NOT** disable sandboxing, just doesn't enable auto mode - **Important:** The `sandbox` parameter is a convenience flag, not a security control **Granular Control Parameters:** - `sandboxMode`: Controls file system access level - `approvalPolicy`: Controls when user approval is required - `fullAuto`: Shorthand for `sandboxMode: "workspace-write"` + `approvalPolicy: "on-failure"` - `yolo`: ⚠️ Bypasses all safety checks (dangerous, not recommended) #### Sandbox Modes | Mode | Description | Use Case | | --------------------- | ------------------------------------ | ------------------------------------------------- | | `read-only` | Analysis only, no file modifications | Code review, exploration, documentation reading | | `workspace-write` | Can modify files in workspace | Most development tasks, refactoring, bug fixes | | `danger-full-access` | Full system access including network | Advanced automation, CI/CD pipelines | #### Approval Policies | Policy | Description | When to Use | | ------------- | -------------------------------- | ----------------------------------- | | `never` | No approvals required | Fully trusted automation | | `on-request` | Ask before every action | Maximum control, manual review | | `on-failure` | Only ask when operations fail | Balanced automation (recommended) | | `untrusted` | Maximum paranoia mode | Untrusted code or high-risk changes | #### Configuration Examples **Example 1: Balanced Automation (Recommended)** ```javascript { "approvalPolicy": "on-failure", "sandboxMode": "workspace-write", // Auto-set if omitted in v1.2+ "model": "gpt-5-codex", "prompt": "refactor @src/utils for better performance" } ``` **Example 2: Quick Automation (Convenience Mode)** ```javascript { "sandbox": true, // Equivalent to fullAuto: true "model": "gpt-5-codex", "prompt": "fix type errors in @src/" } ``` **Example 3: Read-Only Analysis** ```javascript { "sandboxMode": "read-only", "model": "gpt-5-codex", "prompt": "analyze @src/ and explain the architecture" } ``` #### Smart Defaults (v1.2+) Starting from version 1.2.0, the server automatically applies intelligent defaults to prevent permission errors: - ✅ If `approvalPolicy` is set but `sandboxMode` is not → auto-sets `sandboxMode: "workspace-write"` - ✅ If `search: true` or `oss: true` → auto-sets `sandboxMode: "workspace-write"` (for network access) - ✅ All commands include `--skip-git-repo-check` to prevent errors in non-git environments #### Troubleshooting Permission Errors If you encounter `❌ Permission Error: Operation blocked by sandbox policy`: **Check 1: Verify sandboxMode** ```bash # Ensure you're not using read-only mode for write operations { "sandboxMode": "workspace-write", // Not "read-only" "approvalPolicy": "on-failure" } ``` **Check 2: Use convenience flags** ```bash # Let the server handle defaults { "sandbox": true, // Simple automation "prompt": "your task" } ``` **Check 3: Update to latest version** ```bash # v1.2+ includes smart defaults to prevent permission errors npm install -g @cexll/codex-mcp-server@latest ``` #### Common Issues **Issue 1: MCP Tool Timeout Error** If you encounter timeout errors when using Codex MCP tools: ```bash # 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 ``` Add this to your shell profile (`~/.bashrc`, `~/.zshrc`, or PowerShell profile) to make it permanent. **Issue 2: Codex Cannot Write Files** If Codex responds with permission errors like "Operation blocked by sandbox policy" or "rejected by user approval settings", configure your Codex CLI settings: Create or edit `~/.codex/config.toml`: ```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 ``` **⚠️ Security Warning**: The `danger-full-access` mode grants Codex full file system access. Only use this configuration in trusted environments and for tasks you fully understand. **Configuration File Locations:** - **macOS/Linux**: `~/.codex/config.toml` - **Windows**: `%USERPROFILE%\.codex\config.toml` After updating the configuration, restart your MCP client (Claude Desktop, Claude Code, etc.). #### Basic Examples - `use codex to create and run a Python script that processes data` - `ask codex to safely test @script.py and explain what it does` **Default Behavior:** - All `codex exec` commands automatically include `--skip-git-repo-check` to avoid unnecessary git repository checks, as not all execution environments are git repositories. - This prevents permission errors when running Codex in non-git directories or when git checks would interfere with automation. ### Advanced Examples ```javascript // 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/'; ``` ### Tools (for the AI) These tools are designed to be used by the AI assistant. #### Core Tools - **`ask-codex`**: Sends a prompt to Codex via `codex exec`. - Supports `@` file references for including file content - Optional `model` parameter - available models: - `gpt-5-codex` (default, optimized for coding) - `gpt-5` (general purpose, fast reasoning) - `o3` (smartest, deep reasoning) - `o4-mini` (fast & efficient) - `codex-1` (o3-based for software engineering) - `codex-mini-latest` (low-latency code Q&A) - `gpt-4.1` (also available) - `sandbox=true` enables `--full-auto` mode - `changeMode=true` returns structured OLD/NEW edits - Supports approval policies and sandbox modes - **Automatically includes `--skip-git-repo-check`** to prevent permission errors in non-git environments - **`brainstorm`**: Generate novel ideas with structured methodologies. - Multiple frameworks: divergent, convergent, SCAMPER, design-thinking, lateral - Domain-specific context (software, business, creative, research, product, marketing) - Supports same models as `ask-codex` (default: `gpt-5-codex`) - Configurable idea count and analysis depth - Includes feasibility, impact, and innovation scoring - Example: `brainstorm prompt:"ways to improve code review process" domain:"software" methodology:"scamper"` - **`ping`**: A simple test tool that echoes back a message. - Use to verify MCP connection is working - Example: `/codex-cli:ping (MCP) "Hello from Codex MCP!"` - **`help`**: Shows the Codex CLI help text and available commands. #### Advanced Tools - **`fetch-chunk`**: Retrieves cached chunks from changeMode responses. - Used for paginating large structured edit responses - Requires `cacheKey` and `chunkIndex` parameters - **`timeout-test`**: Test tool for timeout prevention. - Runs for a specified duration in milliseconds - Useful for testing long-running operations ### Slash Commands (for the User) You can use these commands directly in Claude Code's interface (compatibility with other clients has not been tested). - **/analyze**: Analyzes files or directories using Codex, or asks general questions. - **`prompt`** (required): The analysis prompt. Use `@` syntax to include files (e.g., `/analyze prompt:@src/ summarize this directory`) or ask general questions (e.g., `/analyze prompt:Please use a web search to find the latest news stories`). - **/sandbox**: Safely tests code or scripts with Codex approval modes. - **`prompt`** (required): Code testing request (e.g., `/sandbox prompt:Create and run a Python script that processes CSV data` or `/sandbox prompt:@script.py Test this script safely`). - **/help**: Displays the Codex CLI help information. - **/ping**: Tests the connection to the server. - **`message`** (optional): A message to echo back. ## Recent Updates ### v1.2.4 (2025-10-27) **🔧 Major Improvement:** - **Windows Compatibility Enhancement**: Replaced Node.js native `spawn()` with industry-standard `cross-spawn` package - Root cause: Previous `shell: true` fix still failed on some Windows configurations - Solution: Use `cross-spawn` (50M+ weekly downloads, used by Webpack/Jest) for automatic Windows `.cmd` handling - Benefits: - Zero configuration required for Windows users - Automatic handling of `.cmd`, `.ps1`, and `.exe` extensions - Compatible with both CMD and PowerShell environments - <5ms performance overhead - Dependencies: Added `cross-spawn@^7.0.6` and `@types/cross-spawn` **🐛 Bug Fixes:** - Enhanced ENOENT error diagnostics with Windows-specific 4-step troubleshooting guide - Added optional chaining for `stdout`/`stderr` to handle null values in TypeScript strict mode **📝 Documentation:** - Added comprehensive Windows troubleshooting section in docs - Documented `spawn codex ENOENT` error resolution steps ### v1.2.3 (2025-10-27) **🐛 Bug Fixes:** - **Windows Compatibility**: Fixed Codex CLI detection failing on Windows despite proper installation - Root cause: `spawn()` with `shell: false` couldn't resolve `.cmd` extensions on Windows - Solution: Enabled shell mode for cross-platform command execution - Impact: Zero performance impact (~10ms overhead), maintains security with array-form arguments - Platforms verified: Windows, macOS, Linux via GitHub Actions CI **📝 Documentation:** - Updated all package references from `@trishchuk/codex-mcp-tool` to `@cexll/codex-mcp-server` - Enhanced cross-platform setup instructions **🔍 Testing:** - CI/CD now validates on Ubuntu, macOS, and Windows across Node.js 18.x, 20.x, and 22.x ### v1.2.2 & Earlier - Smart sandbox mode defaults to prevent permission errors - Enhanced debug information for troubleshooting - Automatic `--skip-git-repo-check` flag for non-git environments - Web search integration with feature flags - Structured change mode with pagination support ## Platform Support | Platform | Status | Notes | |----------|--------|-------| | **Windows** | ✅ Fully Supported | Enhanced in v1.2.4 with cross-spawn | | **macOS** | ✅ Fully Supported | Tested on Darwin 23.5.0+ | | **Linux** | ✅ Fully Supported | Tested on Ubuntu Latest | **Minimum Requirements:** - Node.js v18.0.0 or higher - Codex CLI installed and authenticated (`npm install -g @openai/codex`) ## Acknowledgments This project was inspired by the excellent work from [jamubc/gemini-mcp-tool](https://github.com/jamubc/gemini-mcp-tool). Special thanks to [@jamubc](https://github.com/jamubc) for the original MCP server architecture and implementation patterns. ## Contributing Contributions are welcome! Please submit pull requests or report issues through GitHub. ## License This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. **Disclaimer:** This is an unofficial, third-party tool and is not affiliated with, endorsed, or sponsored by OpenAI.