{"_id":"@panaalexandrucristian88/codex-mcp-server","name":"@panaalexandrucristian88/codex-mcp-server","dist-tags":{"latest":"1.3.0"},"versions":{"1.3.0":{"name":"@panaalexandrucristian88/codex-mcp-server","version":"1.3.0","description":"MCP server for Codex CLI integration","type":"module","main":"dist/index.js","bin":{"codex-mcp":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsc && node dist/index.js","test":"echo \"No tests yet\" && exit 0","lint":"tsc --noEmit","format":"prettier --write \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","format:check":"prettier --check \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","prepublishOnly":"echo '⚠️ Remember to test locally first!' && npm run build","docs:dev":"vitepress dev docs","docs:build":"vitepress build docs","docs:preview":"vitepress preview docs"},"keywords":["mcp","modelcontextprotocol","codex","cli","ai","llm","server","tool","typescript","nodejs","integration","automation"],"author":{"name":"Taras Trishchuk"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/cexll/codex-mcp-server.git"},"bugs":{"url":"https://github.com/cexll/codex-mcp-server/issues"},"homepage":"https://github.com/cexll/codex-mcp-server#readme","engines":{"node":">=18.0.0"},"dependencies":{"@modelcontextprotocol/sdk":"^0.6.1","cross-spawn":"^7.0.6","zod":"^3.25.76","zod-to-json-schema":"^3.24.6"},"devDependencies":{"@types/cross-spawn":"^6.0.6","@types/inquirer":"^9.0.0","@types/node":"^18.19.124","archiver":"^7.0.1","mermaid":"^11.9.0","prettier":"^3.6.2","prismjs":"^1.30.0","tsx":"^4.20.5","typescript":"^5.0.0","vitepress":"^1.6.4","vitepress-plugin-mermaid":"^2.0.17"},"publishConfig":{"access":"public"},"_id":"@panaalexandrucristian88/codex-mcp-server@1.3.0","gitHead":"19fbc1b6441f4f8888cf5b45fcb427a379e05632","types":"./dist/index.d.ts","_nodeVersion":"20.15.0","_npmVersion":"10.7.0","dist":{"integrity":"sha512-ob5lIk3VP9Faj7Zfq44MZkCHKCciG4va80n6ilbkvDCpJyF3gi7xNs2WgltbN+4ZCrjPO7LXTJsoB+Bf7aADOQ==","shasum":"2e5fff077b133ced33b7b971bd73144027b04851","tarball":"https://registry.npmjs.org/@panaalexandrucristian88/codex-mcp-server/-/codex-mcp-server-1.3.0.tgz","fileCount":91,"unpackedSize":251657,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC6BdjEtBIJB5NUhvzwC5nT6YmE7T9CpaIRGa9vxDnmXgIgdJTxNzSYGOtjzlcaOr0D3ZPKIBWEoIQGWnSi49kmGus="}]},"_npmUser":{"name":"panaalexandrucristian","email":"pana.alexandru.cristian@gmail.com"},"directories":{},"maintainers":[{"name":"panaalexandrucristian","email":"pana.alexandru.cristian@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/codex-mcp-server_1.3.0_1769893433804_0.44548558770102664"},"_hasShrinkwrap":false}},"time":{"created":"2026-01-31T21:03:53.706Z","1.3.0":"2026-01-31T21:03:53.979Z","modified":"2026-01-31T21:03:54.217Z"},"maintainers":[{"name":"panaalexandrucristian","email":"pana.alexandru.cristian@gmail.com"}],"description":"MCP server for Codex CLI integration","homepage":"https://github.com/cexll/codex-mcp-server#readme","keywords":["mcp","modelcontextprotocol","codex","cli","ai","llm","server","tool","typescript","nodejs","integration","automation"],"repository":{"type":"git","url":"git+https://github.com/cexll/codex-mcp-server.git"},"author":{"name":"Taras Trishchuk"},"bugs":{"url":"https://github.com/cexll/codex-mcp-server/issues"},"license":"MIT","readme":"# Codex MCP Tool\n\n\n\n[](https://github.com/x51xxx/codex-mcp-tool/releases)\n[](https://www.npmjs.com/package/@panaalexandrucristian88/codex-mcp-server)\n[](https://www.npmjs.com/package/@panaalexandrucristian88/codex-mcp-server)\n[](https://opensource.org/licenses/MIT)\n[](https://github.com/x51xxx/codex-mcp-tool)\n\n
\n\nCodex 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.\n\n> **Latest Release (v1.3.0)**: Performance Release - Parallel batch execution (3-5x speedup), async I/O, progress debouncing, and intelligent caching throughout. [See changelog](#recent-updates)\n\n- Ask Codex questions from your MCP client, or brainstorm ideas programmatically.\n\n\n ![\"Codex](\"https://glama.ai/mcp/servers/@panaalexandrucristian88/codex-mcp-server/badge\")
\n\n\n## TLDR: [](#) + Codex CLI\n\nGoal: Use Codex directly from your MCP-enabled editor to analyze and edit code efficiently.\n\n## Prerequisites\n\nBefore using this tool, ensure you have:\n\n1. **[Node.js](https://nodejs.org/)** (v18.0.0 or higher)\n2. **[Codex CLI](https://github.com/openai/codex)** installed and authenticated\n\n> **✅ Cross-Platform Support**: Fully tested and working on Windows, macOS, and Linux (v1.2.4+)\n\n### One-Line Setup\n\n```bash\nclaude mcp add codex-cli -- npx -y @panaalexandrucristian88/codex-mcp-server\n```\n\n### Verify Installation\n\nType `/mcp` inside Claude Code to verify the Codex MCP is active.\n\n---\n\n### Alternative: Import from Claude Desktop\n\nIf you already have it configured in Claude Desktop:\n\n1. Add to your Claude Desktop config:\n\n```json\n\"codex-cli\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@panaalexandrucristian88/codex-mcp-server\"]\n}\n```\n\n2. Import to Claude Code:\n\n```bash\nclaude mcp add-from-claude-desktop\n```\n\n## Configuration\n\nRegister the MCP server with your MCP client:\n\n### For NPX Usage (Recommended)\n\nAdd this configuration to your Claude Desktop config file:\n\n```json\n{\n \"mcpServers\": {\n \"codex-cli\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@panaalexandrucristian88/codex-mcp-server\"]\n }\n }\n}\n```\n\n### For Global Installation\n\nIf you installed globally, use this configuration instead:\n\n```json\n{\n \"mcpServers\": {\n \"codex-cli\": {\n \"command\": \"codex-mcp\"\n }\n }\n}\n```\n\n**Configuration File Locations:**\n\n- **Claude Desktop**:\n - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n - **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n - **Linux**: `~/.config/claude/claude_desktop_config.json`\n\nAfter updating the configuration, restart your terminal session.\n\n## Example Workflow\n\n- Natural language: \"use codex to explain index.html\", \"understand this repo with @src\", \"look for vulnerabilities and suggest fixes\"\n- Claude Code: Type `/codex-cli` to access the MCP server tools.\n\n## Usage Examples\n\n### Model Selection\n\n```javascript\n// Use the default gpt-5-codex model\n'explain the architecture of @src/';\n\n// Use gpt-5 for fast general purpose reasoning\n'use codex with model gpt-5 to analyze @config.json';\n\n// Use o3 for deep reasoning tasks\n'use codex with model o3 to analyze complex algorithm in @algorithm.py';\n\n// Use o4-mini for quick tasks\n'use codex with model o4-mini to add comments to @utils.js';\n\n// Use codex-1 for software engineering\n'use codex with model codex-1 to refactor @legacy-code.js';\n```\n\n### With File References (using @ syntax)\n\n- `ask codex to analyze @src/main.ts and explain what it does`\n- `use codex to summarize @. the current directory`\n- `analyze @package.json and list dependencies`\n\n### General Questions (without files)\n\n- `ask codex to explain div centering`\n- `ask codex about best practices for React development related to @src/components/Button.tsx`\n\n### Brainstorming & Ideation\n\n- `brainstorm ways to optimize our CI/CD pipeline using SCAMPER method`\n- `use codex to brainstorm 10 innovative features for our app with feasibility analysis`\n- `ask codex to generate product ideas for the healthcare domain with design-thinking approach`\n\n### Codex Approvals & Sandbox\n\nCodex CLI supports fine-grained control over permissions and approvals through sandbox modes and approval policies.\n\n#### Understanding Parameters\n\n**The `sandbox` Parameter (Convenience Flag):**\n\n- `sandbox: true` → Enables **fullAuto** mode (equivalent to `fullAuto: true`)\n- `sandbox: false` (default) → Does **NOT** disable sandboxing, just doesn't enable auto mode\n- **Important:** The `sandbox` parameter is a convenience flag, not a security control\n\n**Granular Control Parameters:**\n\n- `sandboxMode`: Controls file system access level\n- `approvalPolicy`: Controls when user approval is required\n- `fullAuto`: Shorthand for `sandboxMode: \"workspace-write\"` + `approvalPolicy: \"on-failure\"`\n- `yolo`: ⚠️ Bypasses all safety checks (dangerous, not recommended)\n\n#### Sandbox Modes\n\n| Mode | Description | Use Case |\n| --------------------- | ------------------------------------ | ------------------------------------------------- |\n| `read-only` | Analysis only, no file modifications | Code review, exploration, documentation reading |\n| `workspace-write` | Can modify files in workspace | Most development tasks, refactoring, bug fixes |\n| `danger-full-access` | Full system access including network | Advanced automation, CI/CD pipelines |\n\n#### Approval Policies\n\n| Policy | Description | When to Use |\n| ------------- | -------------------------------- | ----------------------------------- |\n| `never` | No approvals required | Fully trusted automation |\n| `on-request` | Ask before every action | Maximum control, manual review |\n| `on-failure` | Only ask when operations fail | Balanced automation (recommended) |\n| `untrusted` | Maximum paranoia mode | Untrusted code or high-risk changes |\n\n#### Configuration Examples\n\n**Example 1: Balanced Automation (Recommended)**\n\n```javascript\n{\n \"approvalPolicy\": \"on-failure\",\n \"sandboxMode\": \"workspace-write\", // Auto-set if omitted in v1.2+\n \"model\": \"gpt-5-codex\",\n \"prompt\": \"refactor @src/utils for better performance\"\n}\n```\n\n**Example 2: Quick Automation (Convenience Mode)**\n\n```javascript\n{\n \"sandbox\": true, // Equivalent to fullAuto: true\n \"model\": \"gpt-5-codex\",\n \"prompt\": \"fix type errors in @src/\"\n}\n```\n\n**Example 3: Read-Only Analysis**\n\n```javascript\n{\n \"sandboxMode\": \"read-only\",\n \"model\": \"gpt-5-codex\",\n \"prompt\": \"analyze @src/ and explain the architecture\"\n}\n```\n\n#### Smart Defaults (v1.2+)\n\nStarting from version 1.2.0, the server automatically applies intelligent defaults to prevent permission errors:\n\n- ✅ If `approvalPolicy` is set but `sandboxMode` is not → auto-sets `sandboxMode: \"workspace-write\"`\n- ✅ If `search: true` or `oss: true` → auto-sets `sandboxMode: \"workspace-write\"` (for network access)\n- ✅ All commands include `--skip-git-repo-check` to prevent errors in non-git environments\n\n#### Troubleshooting Permission Errors\n\nIf you encounter `❌ Permission Error: Operation blocked by sandbox policy`:\n\n**Check 1: Verify sandboxMode**\n\n```bash\n# Ensure you're not using read-only mode for write operations\n{\n \"sandboxMode\": \"workspace-write\", // Not \"read-only\"\n \"approvalPolicy\": \"on-failure\"\n}\n```\n\n**Check 2: Use convenience flags**\n\n```bash\n# Let the server handle defaults\n{\n \"sandbox\": true, // Simple automation\n \"prompt\": \"your task\"\n}\n```\n\n**Check 3: Update to latest version**\n\n```bash\n# v1.2+ includes smart defaults to prevent permission errors\nnpm install -g @panaalexandrucristian88/codex-mcp-server@latest\n```\n\n#### Common Issues\n\n**Issue 1: MCP Tool Timeout Error**\n\nIf you encounter timeout errors when using Codex MCP tools:\n\n```bash\n# Set the MCP tool timeout environment variable (in milliseconds)\nexport MCP_TOOL_TIMEOUT=36000000 # 10 hours\n\n# For Windows (PowerShell):\n$env:MCP_TOOL_TIMEOUT=36000000\n\n# For Windows (CMD):\nset MCP_TOOL_TIMEOUT=36000000\n```\n\nAdd this to your shell profile (`~/.bashrc`, `~/.zshrc`, or PowerShell profile) to make it permanent.\n\n**Issue 2: Codex Cannot Write Files**\n\nIf Codex responds with permission errors like \"Operation blocked by sandbox policy\" or \"rejected by user approval settings\", configure your Codex CLI settings:\n\nCreate or edit `~/.codex/config.toml`:\n\n```toml\n# Dynamically generated Codex configuration\nmodel = \"gpt-5-codex\"\nmodel_reasoning_effort = \"high\"\nmodel_reasoning_summary = \"detailed\"\napproval_policy = \"never\"\nsandbox_mode = \"danger-full-access\"\ndisable_response_storage = true\nnetwork_access = true\n```\n\n**⚠️ 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.\n\n**Configuration File Locations:**\n- **macOS/Linux**: `~/.codex/config.toml`\n- **Windows**: `%USERPROFILE%\\.codex\\config.toml`\n\nAfter updating the configuration, restart your MCP client (Claude Desktop, Claude Code, etc.).\n\n#### Basic Examples\n\n- `use codex to create and run a Python script that processes data`\n- `ask codex to safely test @script.py and explain what it does`\n\n**Default Behavior:**\n\n- All `codex exec` commands automatically include `--skip-git-repo-check` to avoid unnecessary git repository checks, as not all execution environments are git repositories.\n- This prevents permission errors when running Codex in non-git directories or when git checks would interfere with automation.\n\n### Advanced Examples\n\n```javascript\n// Using ask-codex with specific model\n'ask codex using gpt-5 to refactor @utils/database.js for better performance';\n\n// Brainstorming with constraints\n\"brainstorm solutions for reducing API latency with constraints: 'must use existing infrastructure, budget under $5k'\";\n\n// Change mode for structured edits\n'use codex in change mode to update all console.log to use winston logger in @src/';\n```\n\n### Tools (for the AI)\n\nThese tools are designed to be used by the AI assistant.\n\n#### Core Tools\n\n- **`ask-codex`**: Sends a prompt to Codex via `codex exec`.\n - Supports `@` file references for including file content\n - Optional `model` parameter - available models:\n - `gpt-5-codex` (default, optimized for coding)\n - `gpt-5` (general purpose, fast reasoning)\n - `o3` (smartest, deep reasoning)\n - `o4-mini` (fast & efficient)\n - `codex-1` (o3-based for software engineering)\n - `codex-mini-latest` (low-latency code Q&A)\n - `gpt-4.1` (also available)\n - `sandbox=true` enables `--full-auto` mode\n - `changeMode=true` returns structured OLD/NEW edits\n - Supports approval policies and sandbox modes\n - **Automatically includes `--skip-git-repo-check`** to prevent permission errors in non-git environments\n\n- **`brainstorm`**: Generate novel ideas with structured methodologies.\n - Multiple frameworks: divergent, convergent, SCAMPER, design-thinking, lateral\n - Domain-specific context (software, business, creative, research, product, marketing)\n - Supports same models as `ask-codex` (default: `gpt-5-codex`)\n - Configurable idea count and analysis depth\n - Includes feasibility, impact, and innovation scoring\n - Example: `brainstorm prompt:\"ways to improve code review process\" domain:\"software\" methodology:\"scamper\"`\n\n- **`ping`**: A simple test tool that echoes back a message.\n - Use to verify MCP connection is working\n - Example: `/codex-cli:ping (MCP) \"Hello from Codex MCP!\"`\n\n- **`help`**: Shows the Codex CLI help text and available commands.\n\n#### Advanced Tools\n\n- **`batch-codex`**: Delegate multiple atomic tasks to Codex for batch processing.\n - Ideal for repetitive operations, mass refactoring, and automated code transformations\n - Supports parallel execution with `parallel: true` (up to 5 concurrent tasks)\n - Configurable `stopOnError` behavior for error handling\n - Returns aggregated results with success/failure counts\n\n- **`fetch-chunk`**: Retrieves cached chunks from changeMode responses.\n - Used for paginating large structured edit responses\n - Requires `cacheKey` and `chunkIndex` parameters\n\n- **`timeout-test`**: Test tool for timeout prevention.\n - Runs for a specified duration in milliseconds\n - Useful for testing long-running operations\n\n### Slash Commands (for the User)\n\nYou can use these commands directly in Claude Code's interface (compatibility with other clients has not been tested).\n\n- **/analyze**: Analyzes files or directories using Codex, or asks general questions.\n - **`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`).\n- **/sandbox**: Safely tests code or scripts with Codex approval modes.\n - **`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`).\n- **/help**: Displays the Codex CLI help information.\n- **/ping**: Tests the connection to the server.\n - **`message`** (optional): A message to echo back.\n\n## Recent Updates\n\n### v1.3.0 (2026-01-31)\n\n**⚡ Performance Release:**\n- **Parallel Batch Execution**: `batch-codex` now supports true parallel execution with concurrency limit of 5, delivering 3-5x speedup for batch operations\n- **Async I/O for Chunk Cache**: Converted from synchronous to async file operations using `fs.promises`, reducing cache latency by 50-100ms per operation\n- **Progress Callback Debouncing**: 100ms interval batching reduces callback frequency by 80-90%, minimizing event loop contention\n- **Tool Definitions Memoization**: Cached JSON schema generation saves 5-10ms per `tools/list` request\n- **Project Root Caching**: 60-second TTL cache for `findProjectRoot()` lookups, reducing tool execution latency by 20-50ms\n- **Exponential Backoff Cap**: Retry delays now capped at 30 seconds maximum to prevent excessive waits\n- **Memory Leak Prevention**: Probabilistic cleanup for orphaned logger entries in long-running sessions\n- **Centralized Timeouts**: New `TIMEOUTS` constants (QUICK: 60s, STANDARD: 180s, EXTENDED: 600s) for consistent timeout configuration\n\n### v1.2.4 (2025-10-27)\n\n**🔧 Major Improvement:**\n- **Windows Compatibility Enhancement**: Replaced Node.js native `spawn()` with industry-standard `cross-spawn` package\n - Root cause: Previous `shell: true` fix still failed on some Windows configurations\n - Solution: Use `cross-spawn` (50M+ weekly downloads, used by Webpack/Jest) for automatic Windows `.cmd` handling\n - Benefits:\n - Zero configuration required for Windows users\n - Automatic handling of `.cmd`, `.ps1`, and `.exe` extensions\n - Compatible with both CMD and PowerShell environments\n - <5ms performance overhead\n - Dependencies: Added `cross-spawn@^7.0.6` and `@types/cross-spawn`\n\n**🐛 Bug Fixes:**\n- Enhanced ENOENT error diagnostics with Windows-specific 4-step troubleshooting guide\n- Added optional chaining for `stdout`/`stderr` to handle null values in TypeScript strict mode\n\n**📝 Documentation:**\n- Added comprehensive Windows troubleshooting section in docs\n- Documented `spawn codex ENOENT` error resolution steps\n\n### v1.2.3 (2025-10-27)\n\n**🐛 Bug Fixes:**\n- **Windows Compatibility**: Fixed Codex CLI detection failing on Windows despite proper installation\n - Root cause: `spawn()` with `shell: false` couldn't resolve `.cmd` extensions on Windows\n - Solution: Enabled shell mode for cross-platform command execution\n - Impact: Zero performance impact (~10ms overhead), maintains security with array-form arguments\n - Platforms verified: Windows, macOS, Linux via GitHub Actions CI\n\n**📝 Documentation:**\n- Updated all package references from `@trishchuk/codex-mcp-tool` to `@panaalexandrucristian88/codex-mcp-server`\n- Enhanced cross-platform setup instructions\n\n**🔍 Testing:**\n- CI/CD now validates on Ubuntu, macOS, and Windows across Node.js 18.x, 20.x, and 22.x\n\n### v1.2.2 & Earlier\n\n- Smart sandbox mode defaults to prevent permission errors\n- Enhanced debug information for troubleshooting\n- Automatic `--skip-git-repo-check` flag for non-git environments\n- Web search integration with feature flags\n- Structured change mode with pagination support\n\n## Performance Optimizations\n\nThe MCP server includes several performance optimizations for high-throughput scenarios:\n\n- **Parallel batch execution** - Up to 5 concurrent tasks with intelligent concurrency limiter, delivering 3-5x speedup for batch operations\n- **Async I/O for chunk caching** - Non-blocking file operations with deferred cleanup, eliminating event loop blocking\n- **Progress callback debouncing** - 100ms interval batching reduces callback frequency by 80-90%\n- **Tool definitions memoization** - Cached schema generation eliminates redundant JSON serialization on repeated `tools/list` calls\n- **Project root caching** - 60-second TTL cache for filesystem scans, reducing tool execution latency\n- **Centralized timeout configuration** - Configurable timeout tiers (QUICK: 60s, STANDARD: 180s, EXTENDED: 600s)\n\n## Platform Support\n\n| Platform | Status | Notes |\n|----------|--------|-------|\n| **Windows** | ✅ Fully Supported | Enhanced in v1.2.4 with cross-spawn |\n| **macOS** | ✅ Fully Supported | Tested on Darwin 23.5.0+ |\n| **Linux** | ✅ Fully Supported | Tested on Ubuntu Latest |\n\n**Minimum Requirements:**\n- Node.js v18.0.0 or higher\n- Codex CLI installed and authenticated (`npm install -g @openai/codex`)\n\n## Acknowledgments\n\nThis 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.\n\n## Contributing\n\nContributions are welcome! Please submit pull requests or report issues through GitHub.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n**Disclaimer:** This is an unofficial, third-party tool and is not affiliated with, endorsed, or sponsored by OpenAI.\n","readmeFilename":"README.md","_rev":"1-b56a09d361a3f4e44338d41bea3f4761"}