{"_id":"@cexll/codex-mcp-server","_rev":"6-b2930da18098e353438280ae26831c1d","name":"@cexll/codex-mcp-server","dist-tags":{"latest":"1.2.5"},"versions":{"1.2.0":{"name":"@cexll/codex-mcp-server","version":"1.2.0","keywords":["mcp","modelcontextprotocol","codex","cli","ai","llm","server","tool","typescript","nodejs","integration","automation"],"author":{"name":"Taras Trishchuk"},"license":"MIT","_id":"@cexll/codex-mcp-server@1.2.0","maintainers":[{"name":"cexll","email":"evanxian9@gmail.com"}],"homepage":"https://github.com/cexll/codex-mcp-server#readme","bugs":{"url":"https://github.com/cexll/codex-mcp-server/issues"},"bin":{"codex-mcp":"dist/index.js"},"dist":{"shasum":"afba5c7723ee0ab02182579a2d8de7fb2b686d6e","tarball":"https://registry.npmjs.org/@cexll/codex-mcp-server/-/codex-mcp-server-1.2.0.tgz","fileCount":91,"integrity":"sha512-qOMEqEJSWB5LkFsF9Qj941cU1zX96OuEoc2um5S6bTuaaw9njBE/kG27z3+Unxf+bHquMW8LXgXnSLaZeHS+HQ==","signatures":[{"sig":"MEUCIQDQ5w34NoZzE0T3wmOIzcd3Phr/cJ1tiilXrYVZwrOTkQIgaiaoEwaROZOD6F/iO6AbTgZceVZb/G9wuiA/Wa9D/T8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":228800},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"16b56770a7a481c8794bde0b2b73ebdbcdbd3c74","scripts":{"dev":"tsc && node dist/index.js","lint":"tsc --noEmit","test":"echo \"No tests yet\" && exit 0","build":"tsc","start":"node dist/index.js","format":"prettier --write \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","docs:dev":"vitepress dev docs","docs:build":"vitepress build docs","docs:preview":"vitepress preview docs","format:check":"prettier --check \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","prepublishOnly":"echo '⚠️ Remember to test locally first!' && npm run build"},"_npmUser":{"name":"cexll","email":"evanxian9@gmail.com"},"repository":{"url":"git+https://github.com/cexll/codex-mcp-server.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server for Codex CLI integration","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.25.76","zod-to-json-schema":"^3.24.6","@modelcontextprotocol/sdk":"^0.6.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","mermaid":"^11.9.0","prismjs":"^1.30.0","archiver":"^7.0.1","prettier":"^3.6.2","vitepress":"^1.6.4","typescript":"^5.0.0","@types/node":"^18.19.124","@types/inquirer":"^9.0.0","vitepress-plugin-mermaid":"^2.0.17"},"_npmOperationalInternal":{"tmp":"tmp/codex-mcp-server_1.2.0_1761472714253_0.5805055818947691","host":"s3://npm-registry-packages-npm-production"}},"1.2.1":{"name":"@cexll/codex-mcp-server","version":"1.2.1","keywords":["mcp","modelcontextprotocol","codex","cli","ai","llm","server","tool","typescript","nodejs","integration","automation"],"author":{"name":"Taras Trishchuk"},"license":"MIT","_id":"@cexll/codex-mcp-server@1.2.1","maintainers":[{"name":"cexll","email":"evanxian9@gmail.com"}],"homepage":"https://github.com/cexll/codex-mcp-server#readme","bugs":{"url":"https://github.com/cexll/codex-mcp-server/issues"},"bin":{"codex-mcp":"dist/index.js"},"dist":{"shasum":"be829b8820b62e5cb3fef9692edd90ba67187064","tarball":"https://registry.npmjs.org/@cexll/codex-mcp-server/-/codex-mcp-server-1.2.1.tgz","fileCount":91,"integrity":"sha512-0aae8+U+ymL7kQ1eW3Vfd76un8RtmAw540bjoZXUBVkZBMLuHNtvYuEiLQIs0sD6RRrEAk7s/wSyyJBZ3RSGGA==","signatures":[{"sig":"MEUCIG1T7E61k+YTcGtJuvIuqxhR1lhyshua9CzGgQWAJY14AiEA83OtnzZCqgynJoU2AEJbgoLbu68eYHtBy5dO1AldbaU=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":228800},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"12092ec2df7bd374922f459719ca4d422284a492","scripts":{"dev":"tsc && node dist/index.js","lint":"tsc --noEmit","test":"echo \"No tests yet\" && exit 0","build":"tsc","start":"node dist/index.js","format":"prettier --write \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","docs:dev":"vitepress dev docs","docs:build":"vitepress build docs","docs:preview":"vitepress preview docs","format:check":"prettier --check \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","prepublishOnly":"echo '⚠️ Remember to test locally first!' && npm run build"},"_npmUser":{"name":"cexll","email":"evanxian9@gmail.com"},"repository":{"url":"git+https://github.com/cexll/codex-mcp-server.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server for Codex CLI integration","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.25.76","zod-to-json-schema":"^3.24.6","@modelcontextprotocol/sdk":"^0.6.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","mermaid":"^11.9.0","prismjs":"^1.30.0","archiver":"^7.0.1","prettier":"^3.6.2","vitepress":"^1.6.4","typescript":"^5.0.0","@types/node":"^18.19.124","@types/inquirer":"^9.0.0","vitepress-plugin-mermaid":"^2.0.17"},"_npmOperationalInternal":{"tmp":"tmp/codex-mcp-server_1.2.1_1761474360411_0.537842748202831","host":"s3://npm-registry-packages-npm-production"}},"1.2.2":{"name":"@cexll/codex-mcp-server","version":"1.2.2","keywords":["mcp","modelcontextprotocol","codex","cli","ai","llm","server","tool","typescript","nodejs","integration","automation"],"author":{"name":"Taras Trishchuk"},"license":"MIT","_id":"@cexll/codex-mcp-server@1.2.2","maintainers":[{"name":"cexll","email":"evanxian9@gmail.com"}],"homepage":"https://github.com/cexll/codex-mcp-server#readme","bugs":{"url":"https://github.com/cexll/codex-mcp-server/issues"},"bin":{"codex-mcp":"dist/index.js"},"dist":{"shasum":"b06cd51c6548713817495a493c53b53b5a43a913","tarball":"https://registry.npmjs.org/@cexll/codex-mcp-server/-/codex-mcp-server-1.2.2.tgz","fileCount":91,"integrity":"sha512-I9cFBq4IrORpwDoWq3vzdMAOEtBNfJnLiAvjHe1t8aLysCCxCmn2GWhEfgqf8zPfg1KezCNJ4CtPDXGGCm131w==","signatures":[{"sig":"MEYCIQD+1YRZ38/waZxqypvGI9nCxKo4rWhRvdtBHJtQvGKG4gIhAKu+Ex+FiQkvNEmqSu/0OiBMkFzfuL2kaVdjIyuHkcao","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":229863},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"3aef403e3443a0ea8d44fac8ed6ac4e452515460","scripts":{"dev":"tsc && node dist/index.js","lint":"tsc --noEmit","test":"echo \"No tests yet\" && exit 0","build":"tsc","start":"node dist/index.js","format":"prettier --write \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","docs:dev":"vitepress dev docs","docs:build":"vitepress build docs","docs:preview":"vitepress preview docs","format:check":"prettier --check \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","prepublishOnly":"echo '⚠️ Remember to test locally first!' && npm run build"},"_npmUser":{"name":"cexll","email":"evanxian9@gmail.com"},"repository":{"url":"git+https://github.com/cexll/codex-mcp-server.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server for Codex CLI integration","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.25.76","zod-to-json-schema":"^3.24.6","@modelcontextprotocol/sdk":"^0.6.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","mermaid":"^11.9.0","prismjs":"^1.30.0","archiver":"^7.0.1","prettier":"^3.6.2","vitepress":"^1.6.4","typescript":"^5.0.0","@types/node":"^18.19.124","@types/inquirer":"^9.0.0","vitepress-plugin-mermaid":"^2.0.17"},"_npmOperationalInternal":{"tmp":"tmp/codex-mcp-server_1.2.2_1761485400069_0.9771981981823585","host":"s3://npm-registry-packages-npm-production"}},"1.2.3":{"name":"@cexll/codex-mcp-server","version":"1.2.3","keywords":["mcp","modelcontextprotocol","codex","cli","ai","llm","server","tool","typescript","nodejs","integration","automation"],"author":{"name":"Taras Trishchuk"},"license":"MIT","_id":"@cexll/codex-mcp-server@1.2.3","maintainers":[{"name":"cexll","email":"evanxian9@gmail.com"}],"homepage":"https://github.com/cexll/codex-mcp-server#readme","bugs":{"url":"https://github.com/cexll/codex-mcp-server/issues"},"bin":{"codex-mcp":"dist/index.js"},"dist":{"shasum":"6a4fe7a8925b0157fadcaa6684c040cf0e347d0c","tarball":"https://registry.npmjs.org/@cexll/codex-mcp-server/-/codex-mcp-server-1.2.3.tgz","fileCount":91,"integrity":"sha512-jfaJ472AKgQIWL5DCaeYoj6MoXZanlknG+M1tkVLd7vYP35suXtCS618MkLjPwiM0ztRiS71RwYQaXMCAInPRA==","signatures":[{"sig":"MEUCIQCwb7i1CjrzR0B1QAe3tjLUuS0eECrsl/fwRH93GsjAPgIgZuai30Grzhq/Jq/JSMZ1IGQW3TBhXYzrYCK9vbbsp0Y=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":229858},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"38bded73727a26c7da12415637fe7b221fcc950c","scripts":{"dev":"tsc && node dist/index.js","lint":"tsc --noEmit","test":"echo \"No tests yet\" && exit 0","build":"tsc","start":"node dist/index.js","format":"prettier --write \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","docs:dev":"vitepress dev docs","docs:build":"vitepress build docs","docs:preview":"vitepress preview docs","format:check":"prettier --check \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","prepublishOnly":"echo '⚠️ Remember to test locally first!' && npm run build"},"_npmUser":{"name":"cexll","email":"evanxian9@gmail.com"},"repository":{"url":"git+https://github.com/cexll/codex-mcp-server.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server for Codex CLI integration","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.25.76","zod-to-json-schema":"^3.24.6","@modelcontextprotocol/sdk":"^0.6.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","mermaid":"^11.9.0","prismjs":"^1.30.0","archiver":"^7.0.1","prettier":"^3.6.2","vitepress":"^1.6.4","typescript":"^5.0.0","@types/node":"^18.19.124","@types/inquirer":"^9.0.0","vitepress-plugin-mermaid":"^2.0.17"},"_npmOperationalInternal":{"tmp":"tmp/codex-mcp-server_1.2.3_1761569153487_0.29548156708301754","host":"s3://npm-registry-packages-npm-production"}},"1.2.4":{"name":"@cexll/codex-mcp-server","version":"1.2.4","keywords":["mcp","modelcontextprotocol","codex","cli","ai","llm","server","tool","typescript","nodejs","integration","automation"],"author":{"name":"Taras Trishchuk"},"license":"MIT","_id":"@cexll/codex-mcp-server@1.2.4","maintainers":[{"name":"cexll","email":"evanxian9@gmail.com"}],"homepage":"https://github.com/cexll/codex-mcp-server#readme","bugs":{"url":"https://github.com/cexll/codex-mcp-server/issues"},"bin":{"codex-mcp":"dist/index.js"},"dist":{"shasum":"f06dd18c76f844075ea5266d59634796f9f9b057","tarball":"https://registry.npmjs.org/@cexll/codex-mcp-server/-/codex-mcp-server-1.2.4.tgz","fileCount":91,"integrity":"sha512-2y1WmhqyzhvvMea4zGg4EgWFStf1RAXiLv6Vnnk9ID1sl+7aYtLbqcEajDavUEZDCdRHwXv2LUChc7pHOeG7tA==","signatures":[{"sig":"MEYCIQDVRRU8Bm43aiTaffisxm4419MDcwRuf20rrwvPOisk0gIhALLnB8DSahMfjoeTwEoxUZQnUAM5lmPML3enMEFq/gco","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":232620},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"97170699fbd0be59d4bb4ab4ed8d41118b28f82d","scripts":{"dev":"tsc && node dist/index.js","lint":"tsc --noEmit","test":"echo \"No tests yet\" && exit 0","build":"tsc","start":"node dist/index.js","format":"prettier --write \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","docs:dev":"vitepress dev docs","docs:build":"vitepress build docs","docs:preview":"vitepress preview docs","format:check":"prettier --check \"src/**/*.{ts,js,json,md}\" \"docs/**/*.{md,json}\" \"*.{md,json}\"","prepublishOnly":"echo '⚠️ Remember to test locally first!' && npm run build"},"_npmUser":{"name":"cexll","email":"evanxian9@gmail.com"},"repository":{"url":"git+https://github.com/cexll/codex-mcp-server.git","type":"git"},"_npmVersion":"10.9.3","description":"MCP server for Codex CLI integration","directories":{},"_nodeVersion":"22.20.0","dependencies":{"zod":"^3.25.76","cross-spawn":"^7.0.6","zod-to-json-schema":"^3.24.6","@modelcontextprotocol/sdk":"^0.6.1"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.5","mermaid":"^11.9.0","prismjs":"^1.30.0","archiver":"^7.0.1","prettier":"^3.6.2","vitepress":"^1.6.4","typescript":"^5.0.0","@types/node":"^18.19.124","@types/inquirer":"^9.0.0","@types/cross-spawn":"^6.0.6","vitepress-plugin-mermaid":"^2.0.17"},"_npmOperationalInternal":{"tmp":"tmp/codex-mcp-server_1.2.4_1761570999262_0.7467579332701324","host":"s3://npm-registry-packages-npm-production"}},"1.2.5":{"name":"@cexll/codex-mcp-server","version":"1.2.5","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":"@cexll/codex-mcp-server@1.2.5","gitHead":"e72c335ce6b489908ee03bec3cd2f5ce750eff62","types":"./dist/index.d.ts","_nodeVersion":"22.20.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-NDSpCModmS3hw4vgYJ9cPRkTiq93zfuCZ1V43VJjFA6Np8rVXtp/z7kwP67G1J5FuGoN2l9jzeDnsa7NCEpZ1Q==","shasum":"ad115ce457acbd57b819e2a70ad08979b17065ba","tarball":"https://registry.npmjs.org/@cexll/codex-mcp-server/-/codex-mcp-server-1.2.5.tgz","fileCount":91,"unpackedSize":233689,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIDot8IsZyfNjQGlihSCBqswXji8i1bunB0fUKvslzwgFAiEAhdBWptNp10DTW3ngB1GZe51ucsMY0eL5jTqY2NJzw3E="}]},"_npmUser":{"name":"cexll","email":"evanxian9@gmail.com"},"directories":{},"maintainers":[{"name":"cexll","email":"evanxian9@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/codex-mcp-server_1.2.5_1761635414140_0.18049667820905757"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-26T09:58:34.193Z","modified":"2025-10-28T07:10:14.516Z","1.2.0":"2025-10-26T09:58:34.456Z","1.2.1":"2025-10-26T10:26:00.667Z","1.2.2":"2025-10-26T13:30:00.315Z","1.2.3":"2025-10-27T12:45:53.723Z","1.2.4":"2025-10-27T13:16:39.432Z","1.2.5":"2025-10-28T07:10:14.333Z"},"bugs":{"url":"https://github.com/cexll/codex-mcp-server/issues"},"author":{"name":"Taras Trishchuk"},"license":"MIT","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"},"description":"MCP server for Codex CLI integration","maintainers":[{"name":"cexll","email":"evanxian9@gmail.com"}],"readme":"# Codex MCP Tool\n\n\n\n[](https://github.com/x51xxx/codex-mcp-tool/releases)\n[](https://www.npmjs.com/package/@cexll/codex-mcp-server)\n[](https://www.npmjs.com/package/@cexll/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.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)\n\n- Ask Codex questions from your MCP client, or brainstorm ideas programmatically.\n\n\n ![\"Codex](\"https://glama.ai/mcp/servers/@cexll/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 @cexll/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\", \"@cexll/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\", \"@cexll/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 @cexll/codex-mcp-server@latest\n```\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- **`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.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 `@cexll/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## 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"}