codex-exec-mcp

中文说明

Let Claude (Claude Desktop, Claude Code) or any MCP client hand coding tasks to the Codex CLI as a sub-agent.

Codex runs with your own Codex configuration, so whichever model provider you set up in ~/.codex/config.toml (OpenAI, DeepSeek, a local model, …) does the work. Typical use: Claude writes the spec and checks the result, Codex writes the code, and your Claude usage goes much further.

• Zero dependencies. Plain Node.js. The MCP protocol is implemented directly, so an SDK release cannot break it.
• Old and new MCP clients. Supports both the initialize handshake (2024-11-05 … 2025-11-25) and the stateless 2026-07-28 protocol with server/discover. Responses are validated against the official JSON schemas.
• Survives Codex upgrades. Uses the documented codex exec --json (not the removed codex mcp-server or the experimental app-server). Flags are detected at runtime.
• No client timeouts. codex_run waits up to 45 s, then returns a job_id; codex_status waits again. Long tasks never hit a 60 s tool limit.
• Small replies. Claude gets Codex's final message plus a change summary (files, commands, tokens), not the transcript. Files changed by shell commands are included.
• Lean mode. Turns off Codex plugins and your Codex MCP servers for sub-agent runs only. In one measurement this cut per-request context from ~118k to ~14k tokens.
• Clean process handling. Cancel, timeout or client exit kills Codex and everything it started. Works on Windows, macOS and Linux.

Requirements

• Node.js 18.17+
• Codex CLI (npm i -g @openai/codex). Check that codex exec "say hi" works in a terminal first.

Install

Claude Code: plugin (MCP server + workflow skill)

/plugin marketplace add JaegerY/codex-exec-mcp
/plugin install codex-exec@codex-exec-mcp

The plugin starts the server with lean mode on and adds the codex-delegate skill. Ask "let Codex implement …" and Claude writes a spec, delegates, verifies the result independently and sends defects back to Codex.

Claude Desktop: one command

npm i -g codex-exec-mcp
codex-exec-mcp install --root /path/to/your/projects
# Windows example:
codex-exec-mcp install --root C:\Users\me\projects --windows-sandbox unelevated

This adds an mcpServers.codex entry to Claude Desktop's config (it also finds the config of MSIX-packaged installs (Microsoft Store, WinGet, packaged installers) under %LOCALAPPDATA%\Packages\Claude_*). It backs up the file first, leaves every other entry alone, and uses absolute paths, so PATH problems cannot break it. Running it again updates the entry. Then fully quit Claude Desktop (tray / menu bar → Quit) and start it again. Remove the entry with codex-exec-mcp uninstall.

Not published to npm yet? Clone the repository and run node cli/codex-exec-mcp.js install … from it.

To use the workflow in Claude Desktop too, add skills/codex-delegate/SKILL.md as a skill.

Other MCP clients (Cursor, Windsurf, VS Code, …)

Command node, argument /absolute/path/to/codex-exec-mcp/cli/codex-exec-mcp.js. Settings go in env (see Configuration).

Check it

codex-exec-mcp doctor          # finds Codex, shows detected features; no tokens used
codex-exec-mcp doctor --live   # also runs one tiny real task with your provider

Or ask Claude to call codex_info.

Tools

These three exist so the client can verify Codex's work without trusting Codex to retype anything: put the acceptance script in with workspace_write, have Codex run it, read the real output with codex_output, and review changed files with workspace_read.

Example result:

Implemented retry with backoff in src/http.ts and added tests; npm test passes.

---
status: completed | job_id: j_mbx2k1a3f9 | session_id: 019a5c3e-…
duration: 2m14s | commands: 6 | files changed: 2 | codex tokens: in 48210 (cached 31000) / out 2210
files:
  M src/http.ts
  A test/http.test.ts
commands; verbatim output via codex_output job_id "j_mbx2k1a3f9" command N:
  #5 exit 1 $ npm test
  #6 exit 0 $ npm test
To continue this Codex conversation, call codex_run with session_id "019a5c3e-…".

Pass the latest session_id to continue the same Codex conversation (codex exec resume).

Configuration

All settings are environment variables in the client's env block. install writes the common ones for you.

Saving tokens

Codex sends its whole context with every model request, so a task of N steps costs about N × context. Two things inflate the context:

• Tool definitions from MCP servers and plugins. Models marked supports_search_tool = true in Codex's model catalog load them on demand. Other models, including many third-party models added through a custom models.json, receive every definition in every request.
• Plugin skills and hooks, which add instructions to every request.

A coding sub-agent rarely needs your data MCP servers or browser plugins. With CODEX_MCP_LEAN=1, each run gets -c features.plugins=false plus -c mcp_servers.<name>.enabled=false for every server in ~/.codex/config.toml. Your config file is only read, and Codex used directly is unaffected. codex_info lists what lean mode disables.

Other levers: keep tasks scoped, ask Codex for a short final report, and use a lower reasoning effort for routine work.

Windows notes

• Sandbox. Codex enforces --sandbox on native Windows only when [windows] sandbox is set, either in Codex's config or with CODEX_MCP_WINDOWS_SANDBOX / install --windows-sandbox.
  • elevated runs commands as a separate codexsandbox* account. That account cannot read tools installed per-user under AppData (for example a "just for me" Python install), so python is not found.
  • unelevated runs as your own account with a restricted token. Your tools work, and writes are still limited to the project folder.
• Python temp dirs. Inside the sandbox, tempfile.mkdtemp() creates folders that the sandboxed process cannot write into or delete. Tests that use tempfile fail. Ask Codex to create test folders with os.makedirs inside the project instead; the bundled skill does this. Leftover tmp* folders can be deleted from your normal account.
• If Claude Desktop cannot find node or codex, run install (it writes absolute paths) or set CODEX_MCP_CODEX_PATH.

Troubleshooting

1. codex-exec-mcp doctor --live prints the error and Codex's stderr.
2. Failed runs include Codex's stderr and the log folder. Provider errors (401, wrong base_url, missing API key variable) show up there.
3. Claude Desktop logs: %APPDATA%\Claude\logs\mcp-server-codex.log (Windows; MSIX-packaged install: %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\logs\), ~/Library/Logs/Claude/mcp-server-codex.log (macOS).
4. MSIX-packaged install on Windows (check with Get-AppxPackage *Claude*): the app reads its config from %LOCALAPPDATA%\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json, not %APPDATA%\Claude\. install picks the right file automatically; when editing by hand, use Settings → Developer → Edit Config.
5. If your Codex provider uses env_key, that variable must be visible to this server: set it system-wide or in env.

Security

Codex is an autonomous agent that edits files and runs commands. This server limits where it runs (cwd checks, allowed roots) and passes the sandbox you choose. The isolation itself comes from Codex's sandbox. Keep workspace-write or read-only, set allowed roots, and use it only on projects you trust. danger-full-access stays off unless you opt in.

How it works

Claude ──MCP stdio──▶ codex-exec-mcp ──▶ codex exec --json --cd DIR --sandbox MODE -o last.txt [-c …lean] [resume ID] -
                            ▲                    │  prompt on stdin, JSONL events on stdout
                            └── summary + reply ◀┘

Development

npm test                      # 51 tests against a fake Codex; no network or API key
claude plugin validate .      # plugin + marketplace manifests

test/fixtures/fake-codex.mjs mimics the Codex CLI. Markers in the prompt ([sleep:500], [fail], [hang], [tree], [touch:f], …) choose its behaviour. CI runs on Linux, macOS and Windows with Node 18–24. Please keep the zero-dependency rule.

License

MIT