Skip to content
Back to search

codex-mcp-server

Codex Mcp Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/cexll--codex-mcp-server/badge.svg)](/listings/cexll--codex-mcp-server)

HTML

<a href="/listings/cexll--codex-mcp-server"><img src="/api/listings/cexll--codex-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 455 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Codex MCP Tool
  2. <div align="center">
  3. [![GitHub Release](https://img.shields.io/github/v/release/x51xxx/codex-mcp-tool?logo=github&label=GitHub)](https://github.com/x51xxx/codex-mcp-tool/releases)
  4. [![npm version](https://img.shields.io/npm/v/@cexll/codex-mcp-server)](https://www.npmjs.com/package/@cexll/codex-mcp-server)
  5. [![npm downloads](https://img.shields.io/npm/dt/@cexll/codex-mcp-server)](https://www.npmjs.com/package/@cexll/codex-mcp-server)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  7. [![Open Source](https://img.shields.io/badge/Open%20Source-❤️-red.svg)](https://github.com/x51xxx/codex-mcp-tool)
  8. </div>
  9. 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.
  10. > **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)
  11. - Ask Codex questions from your MCP client, or brainstorm ideas programmatically.
  12. <a href="https://glama.ai/mcp/servers/@cexll/codex-mcp-server">
  13. <img width="380" height="200" src="https://glama.ai/mcp/servers/@cexll/codex-mcp-server/badge" alt="Codex Tool MCP server" />
  14. </a>
  15. ## TLDR: [![Claude](https://img.shields.io/badge/Claude-D97757?logo=claude&logoColor=fff)](#) + Codex CLI
  16. Goal: Use Codex directly from your MCP-enabled editor to analyze and edit code efficiently.
  17. ## Prerequisites
  18. Before using this tool, ensure you have:
  19. 1. **[Node.js](https://nodejs.org/)** (v18.0.0 or higher)
  20. 2. **[Codex CLI](https://github.com/openai/codex)** installed and authenticated
  21. > **✅ Cross-Platform Support**: Fully tested and working on Windows, macOS, and Linux (v1.2.4+)
  22. ### One-Line Setup
  23. ```bash
  24. claude mcp add codex-cli -- npx -y @cexll/codex-mcp-server
  25. ```
  26. ### Verify Installation
  27. Type `/mcp` inside Claude Code to verify the Codex MCP is active.
  28. ---
  29. ### Alternative: Import from Claude Desktop
  30. If you already have it configured in Claude Desktop:
  31. 1. Add to your Claude Desktop config:
  32. ```json
  33. "codex-cli": {
  34. "command": "npx",
  35. "args": ["-y", "@cexll/codex-mcp-server"]
  36. }
  37. ```
  38. 2. Import to Claude Code:
  39. ```bash
  40. claude mcp add-from-claude-desktop
  41. ```
  42. ## Configuration
  43. Register the MCP server with your MCP client:
  44. ### For NPX Usage (Recommended)
  45. Add this configuration to your Claude Desktop config file:
  46. ```json
  47. {
  48. "mcpServers": {
  49. "codex-cli": {
  50. "command": "npx",
  51. "args": ["-y", "@cexll/codex-mcp-server"]
  52. }
  53. }
  54. }
  55. ```
  56. ### For Global Installation
  57. If you installed globally, use this configuration instead:
  58. ```json
  59. {
  60. "mcpServers": {
  61. "codex-cli": {
  62. "command": "codex-mcp"
  63. }
  64. }
  65. }
  66. ```
  67. **Configuration File Locations:**
  68. - **Claude Desktop**:
  69. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  70. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  71. - **Linux**: `~/.config/claude/claude_desktop_config.json`
  72. After updating the configuration, restart your terminal session.
  73. ## Example Workflow
  74. - Natural language: "use codex to explain index.html", "understand this repo with @src", "look for vulnerabilities and suggest fixes"
  75. - Claude Code: Type `/codex-cli` to access the MCP server tools.
  76. ## Usage Examples
  77. ### Model Selection
  78. ```javascript
  79. // Use the default gpt-5-codex model
  80. 'explain the architecture of @src/';
  81. // Use gpt-5 for fast general purpose reasoning
  82. 'use codex with model gpt-5 to analyze @config.json';
  83. // Use o3 for deep reasoning tasks
  84. 'use codex with model o3 to analyze complex algorithm in @algorithm.py';
  85. // Use o4-mini for quick tasks
  86. 'use codex with model o4-mini to add comments to @utils.js';
  87. // Use codex-1 for software engineering
  88. 'use codex with model codex-1 to refactor @legacy-code.js';
  89. ```
  90. ### With File References (using @ syntax)
  91. - `ask codex to analyze @src/main.ts and explain what it does`
  92. - `use codex to summarize @. the current directory`
  93. - `analyze @package.json and list dependencies`
  94. ### General Questions (without files)
  95. - `ask codex to explain div centering`
  96. - `ask codex about best practices for React development related to @src/components/Button.tsx`
  97. ### Brainstorming & Ideation
  98. - `brainstorm ways to optimize our CI/CD pipeline using SCAMPER method`
  99. - `use codex to brainstorm 10 innovative features for our app with feasibility analysis`
  100. - `ask codex to generate product ideas for the healthcare domain with design-thinking approach`
  101. ### Codex Approvals & Sandbox
  102. Codex CLI supports fine-grained control over permissions and approvals through sandbox modes and approval policies.
  103. #### Understanding Parameters
  104. **The `sandbox` Parameter (Convenience Flag):**
  105. - `sandbox: true` → Enables **fullAuto** mode (equivalent to `fullAuto: true`)
  106. - `sandbox: false` (default) → Does **NOT** disable sandboxing, just doesn't enable auto mode
  107. - **Important:** The `sandbox` parameter is a convenience flag, not a security control
  108. **Granular Control Parameters:**
  109. - `sandboxMode`: Controls file system access level
  110. - `approvalPolicy`: Controls when user approval is required
  111. - `fullAuto`: Shorthand for `sandboxMode: "workspace-write"` + `approvalPolicy: "on-failure"`
  112. - `yolo`: ⚠️ Bypasses all safety checks (dangerous, not recommended)
  113. #### Sandbox Modes
  114. | Mode | Description | Use Case |
  115. | --------------------- | ------------------------------------ | ------------------------------------------------- |
  116. | `read-only` | Analysis only, no file modifications | Code review, exploration, documentation reading |
  117. | `workspace-write` | Can modify files in workspace | Most development tasks, refactoring, bug fixes |
  118. | `danger-full-access` | Full system access including network | Advanced automation, CI/CD pipelines |
  119. #### Approval Policies
  120. | Policy | Description | When to Use |
  121. | ------------- | -------------------------------- | ----------------------------------- |
  122. | `never` | No approvals required | Fully trusted automation |
  123. | `on-request` | Ask before every action | Maximum control, manual review |
  124. | `on-failure` | Only ask when operations fail | Balanced automation (recommended) |
  125. | `untrusted` | Maximum paranoia mode | Untrusted code or high-risk changes |
  126. #### Configuration Examples
  127. **Example 1: Balanced Automation (Recommended)**
  128. ```javascript
  129. {
  130. "approvalPolicy": "on-failure",
  131. "sandboxMode": "workspace-write", // Auto-set if omitted in v1.2+
  132. "model": "gpt-5-codex",
  133. "prompt": "refactor @src/utils for better performance"
  134. }
  135. ```
  136. **Example 2: Quick Automation (Convenience Mode)**
  137. ```javascript
  138. {
  139. "sandbox": true, // Equivalent to fullAuto: true
  140. "model": "gpt-5-codex",
  141. "prompt": "fix type errors in @src/"
  142. }
  143. ```
  144. **Example 3: Read-Only Analysis**
  145. ```javascript
  146. {
  147. "sandboxMode": "read-only",
  148. "model": "gpt-5-codex",
  149. "prompt": "analyze @src/ and explain the architecture"
  150. }
  151. ```
  152. #### Smart Defaults (v1.2+)
  153. Starting from version 1.2.0, the server automatically applies intelligent defaults to prevent permission errors:
  154. - ✅ If `approvalPolicy` is set but `sandboxMode` is not → auto-sets `sandboxMode: "workspace-write"`
  155. - ✅ If `search: true` or `oss: true` → auto-sets `sandboxMode: "workspace-write"` (for network access)
  156. - ✅ All commands include `--skip-git-repo-check` to prevent errors in non-git environments
  157. #### Troubleshooting Permission Errors
  158. If you encounter `❌ Permission Error: Operation blocked by sandbox policy`:
  159. **Check 1: Verify sandboxMode**
  160. ```bash
  161. # Ensure you're not using read-only mode for write operations
  162. {
  163. "sandboxMode": "workspace-write", // Not "read-only"
  164. "approvalPolicy": "on-failure"
  165. }
  166. ```
  167. **Check 2: Use convenience flags**
  168. ```bash
  169. # Let the server handle defaults
  170. {
  171. "sandbox": true, // Simple automation
  172. "prompt": "your task"
  173. }
  174. ```
  175. **Check 3: Update to latest version**
  176. ```bash
  177. # v1.2+ includes smart defaults to prevent permission errors
  178. npm install -g @cexll/codex-mcp-server@latest
  179. ```
  180. #### Common Issues
  181. **Issue 1: MCP Tool Timeout Error**
  182. If you encounter timeout errors when using Codex MCP tools:
  183. ```bash
  184. # Set the MCP tool timeout environment variable (in milliseconds)
  185. export MCP_TOOL_TIMEOUT=36000000 # 10 hours
  186. # For Windows (PowerShell):
  187. $env:MCP_TOOL_TIMEOUT=36000000
  188. # For Windows (CMD):
  189. set MCP_TOOL_TIMEOUT=36000000
  190. ```
  191. Add this to your shell profile (`~/.bashrc`, `~/.zshrc`, or PowerShell profile) to make it permanent.
  192. **Issue 2: Codex Cannot Write Files**
  193. If Codex responds with permission errors like "Operation blocked by sandbox policy" or "rejected by user approval settings", configure your Codex CLI settings:
  194. Create or edit `~/.codex/config.toml`:
  195. ```toml
  196. # Dynamically generated Codex configuration
  197. model = "gpt-5-codex"
  198. model_reasoning_effort = "high"
  199. model_reasoning_summary = "detailed"
  200. approval_policy = "never"
  201. sandbox_mode = "danger-full-access"
  202. disable_response_storage = true
  203. network_access = true
  204. ```
  205. **⚠️ 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.
  206. **Configuration File Locations:**
  207. - **macOS/Linux**: `~/.codex/config.toml`
  208. - **Windows**: `%USERPROFILE%\.codex\config.toml`
  209. After updating the configuration, restart your MCP client (Claude Desktop, Claude Code, etc.).
  210. #### Basic Examples
  211. - `use codex to create and run a Python script that processes data`
  212. - `ask codex to safely test @script.py and explain what it does`
  213. **Default Behavior:**
  214. - All `codex exec` commands automatically include `--skip-git-repo-check` to avoid unnecessary git repository checks, as not all execution environments are git repositories.
  215. - This prevents permission errors when running Codex in non-git directories or when git checks would interfere with automation.
  216. ### Advanced Examples
  217. ```javascript
  218. // Using ask-codex with specific model
  219. 'ask codex using gpt-5 to refactor @utils/database.js for better performance';
  220. // Brainstorming with constraints
  221. "brainstorm solutions for reducing API latency with constraints: 'must use existing infrastructure, budget under $5k'";
  222. // Change mode for structured edits
  223. 'use codex in change mode to update all console.log to use winston logger in @src/';
  224. ```
  225. ### Tools (for the AI)
  226. These tools are designed to be used by the AI assistant.
  227. #### Core Tools
  228. - **`ask-codex`**: Sends a prompt to Codex via `codex exec`.
  229. - Supports `@` file references for including file content
  230. - Optional `model` parameter - available models:
  231. - `gpt-5-codex` (default, optimized for coding)
  232. - `gpt-5` (general purpose, fast reasoning)
  233. - `o3` (smartest, deep reasoning)
  234. - `o4-mini` (fast & efficient)
  235. - `codex-1` (o3-based for software engineering)
  236. - `codex-mini-latest` (low-latency code Q&A)
  237. - `gpt-4.1` (also available)
  238. - `sandbox=true` enables `--full-auto` mode
  239. - `changeMode=true` returns structured OLD/NEW edits
  240. - Supports approval policies and sandbox modes
  241. - **Automatically includes `--skip-git-repo-check`** to prevent permission errors in non-git environments
  242. - **`brainstorm`**: Generate novel ideas with structured methodologies.
  243. - Multiple frameworks: divergent, convergent, SCAMPER, design-thinking, lateral
  244. - Domain-specific context (software, business, creative, research, product, marketing)
  245. - Supports same models as `ask-codex` (default: `gpt-5-codex`)
  246. - Configurable idea count and analysis depth
  247. - Includes feasibility, impact, and innovation scoring
  248. - Example: `brainstorm prompt:"ways to improve code review process" domain:"software" methodology:"scamper"`
  249. - **`ping`**: A simple test tool that echoes back a message.
  250. - Use to verify MCP connection is working
  251. - Example: `/codex-cli:ping (MCP) "Hello from Codex MCP!"`
  252. - **`help`**: Shows the Codex CLI help text and available commands.
  253. #### Advanced Tools
  254. - **`fetch-chunk`**: Retrieves cached chunks from changeMode responses.
  255. - Used for paginating large structured edit responses
  256. - Requires `cacheKey` and `chunkIndex` parameters
  257. - **`timeout-test`**: Test tool for timeout prevention.
  258. - Runs for a specified duration in milliseconds
  259. - Useful for testing long-running operations
  260. ### Slash Commands (for the User)
  261. You can use these commands directly in Claude Code's interface (compatibility with other clients has not been tested).
  262. - **/analyze**: Analyzes files or directories using Codex, or asks general questions.
  263. - **`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`).
  264. - **/sandbox**: Safely tests code or scripts with Codex approval modes.
  265. - **`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`).
  266. - **/help**: Displays the Codex CLI help information.
  267. - **/ping**: Tests the connection to the server.
  268. - **`message`** (optional): A message to echo back.
  269. ## Recent Updates
  270. ### v1.2.4 (2025-10-27)
  271. **🔧 Major Improvement:**
  272. - **Windows Compatibility Enhancement**: Replaced Node.js native `spawn()` with industry-standard `cross-spawn` package
  273. - Root cause: Previous `shell: true` fix still failed on some Windows configurations
  274. - Solution: Use `cross-spawn` (50M+ weekly downloads, used by Webpack/Jest) for automatic Windows `.cmd` handling
  275. - Benefits:
  276. - Zero configuration required for Windows users
  277. - Automatic handling of `.cmd`, `.ps1`, and `.exe` extensions
  278. - Compatible with both CMD and PowerShell environments
  279. - <5ms performance overhead
  280. - Dependencies: Added `cross-spawn@^7.0.6` and `@types/cross-spawn`
  281. **🐛 Bug Fixes:**
  282. - Enhanced ENOENT error diagnostics with Windows-specific 4-step troubleshooting guide
  283. - Added optional chaining for `stdout`/`stderr` to handle null values in TypeScript strict mode
  284. **📝 Documentation:**
  285. - Added comprehensive Windows troubleshooting section in docs
  286. - Documented `spawn codex ENOENT` error resolution steps
  287. ### v1.2.3 (2025-10-27)
  288. **🐛 Bug Fixes:**
  289. - **Windows Compatibility**: Fixed Codex CLI detection failing on Windows despite proper installation
  290. - Root cause: `spawn()` with `shell: false` couldn't resolve `.cmd` extensions on Windows
  291. - Solution: Enabled shell mode for cross-platform command execution
  292. - Impact: Zero performance impact (~10ms overhead), maintains security with array-form arguments
  293. - Platforms verified: Windows, macOS, Linux via GitHub Actions CI
  294. **📝 Documentation:**
  295. - Updated all package references from `@trishchuk/codex-mcp-tool` to `@cexll/codex-mcp-server`
  296. - Enhanced cross-platform setup instructions
  297. **🔍 Testing:**
  298. - CI/CD now validates on Ubuntu, macOS, and Windows across Node.js 18.x, 20.x, and 22.x
  299. ### v1.2.2 & Earlier
  300. - Smart sandbox mode defaults to prevent permission errors
  301. - Enhanced debug information for troubleshooting
  302. - Automatic `--skip-git-repo-check` flag for non-git environments
  303. - Web search integration with feature flags
  304. - Structured change mode with pagination support
  305. ## Platform Support
  306. | Platform | Status | Notes |
  307. |----------|--------|-------|
  308. | **Windows** | ✅ Fully Supported | Enhanced in v1.2.4 with cross-spawn |
  309. | **macOS** | ✅ Fully Supported | Tested on Darwin 23.5.0+ |
  310. | **Linux** | ✅ Fully Supported | Tested on Ubuntu Latest |
  311. **Minimum Requirements:**
  312. - Node.js v18.0.0 or higher
  313. - Codex CLI installed and authenticated (`npm install -g @openai/codex`)
  314. ## Acknowledgments
  315. 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.
  316. ## Contributing
  317. Contributions are welcome! Please submit pull requests or report issues through GitHub.
  318. ## License
  319. This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
  320. **Disclaimer:** This is an unofficial, third-party tool and is not affiliated with, endorsed, or sponsored by OpenAI.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.