Skip to main content
Glama

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.

Related MCP server: Rail Connector MCP

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.

install option

Meaning

--root DIR (repeatable)

Folders Codex may always work in. The first one is the default. Strongly recommended; folders open in the client and approved folders are added on top.

--windows-sandbox unelevated

Windows: run commands sandboxed as your user. See Windows notes.

--no-lean

Keep your Codex plugins and MCP servers available to the sub-agent.

--name NAME, --config FILE, --dry-run

Entry name (default codex), another config file, show without writing.

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

Tool

What it does

codex_run

Start a task: prompt, plus optional cwd, sandbox, session_id, model, wait_sec, timeout_sec. Returns the result, or status: running with a job_id.

codex_status

Wait for a job and return its result. Without job_id it lists recent jobs.

codex_cancel

Stop a job and everything it started.

codex_info

Codex path, version, detected features and this server's settings. Uses no tokens.

codex_output

The verbatim output of a command Codex ran (test runs, scripts), taken from the event log, by number (command, negative counts from the end) or by match. Without either it lists the job's commands. No model involved; works after a server restart too.

workspace_read

Read files or list folders inside an allowed workspace directly: exact text with size, sha256 and BOM/CRLF flags. No tokens.

workspace_write

Write files inside an allowed workspace byte for byte (utf8 or base64, optional expected sha256, overwrite off by default, never inside .git). For seeding projects, acceptance scripts and test data. On by default only when CODEX_MCP_ALLOWED_ROOTS is set.

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).

Which folders Codex may work in

cwd must be inside one of these. Every source comes from you, never from the model's tool call:

  1. CODEX_MCP_ALLOWED_ROOTS (install --root).

  2. The folders open in your client. If the client supports MCP roots, the server asks for them after connecting and again whenever they change, and allows them automatically (subfolders included).

  3. Folders you approved before, kept in ~/.codex-exec-mcp/approved-roots.json. Add them with codex-exec-mcp allow DIR, list with codex-exec-mcp allowed, remove with codex-exec-mcp disallow DIR.

  4. A prompt. For any other folder, if the client supports MCP elicitation, it asks you to allow it. "Remember this folder" (on by default) saves it in the approved file.

The filesystem root, your home folder and the Windows system folder are never added by 2–4. codex_info shows what your client offers (client: …; roots: yes/no, elicitation: yes/no) and which folders are currently allowed. Turn the sources off with CODEX_MCP_CLIENT_ROOTS=0, CODEX_MCP_ASK_ROOTS=0 or CODEX_MCP_APPROVED_ROOTS_FILE=off. Without CODEX_MCP_ALLOWED_ROOTS every folder except those three is allowed, as before.

Configuration

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

Variable

Default

Meaning

CODEX_MCP_DEFAULT_CWD

server's working directory

Folder used when a call gives no cwd.

CODEX_MCP_ALLOWED_ROOTS

(any)

Folders cwd must be inside (; on Windows, : elsewhere), in addition to client roots and approved folders. See Which folders Codex may work in.

CODEX_MCP_CLIENT_ROOTS

1

0 stops allowing the folders open in the client (MCP roots).

CODEX_MCP_ASK_ROOTS

1

0 stops asking (MCP elicitation) before using other folders.

CODEX_MCP_APPROVED_ROOTS_FILE

~/.codex-exec-mcp/approved-roots.json

Where approved folders are kept; off disables it.

CODEX_MCP_LEAN

0

1 turns off Codex plugins and the MCP servers in ~/.codex/config.toml for these runs only. See Saving tokens.

CODEX_MCP_LEAN_KEEP

Comma-separated MCP server names to keep in lean mode.

CODEX_MCP_DEFAULT_SANDBOX

workspace-write

read-only, workspace-write or danger-full-access.

CODEX_MCP_ALLOW_DANGER

0

Must be 1 before danger-full-access can be used.

CODEX_MCP_WINDOWS_SANDBOX

(Codex config)

Windows: unelevated, elevated or mxc, passed as -c windows.sandbox=….

CODEX_MCP_DEFAULT_MODEL

(Codex config)

Model passed as --model.

CODEX_MCP_EXTRA_ARGS

[]

JSON array of extra codex exec arguments, e.g. ["-c","model_reasoning_effort=high"].

CODEX_MCP_CODEX_PATH

found on PATH

Full path to codex, codex.cmd, codex.exe or Codex's codex.js.

CODEX_MCP_RUN_WAIT_SEC / CODEX_MCP_STATUS_WAIT_SEC

45

How long one codex_run / codex_status call waits.

CODEX_MCP_TIMEOUT_SEC

1800

Hard limit per Codex run.

CODEX_MCP_MAX_CONCURRENT

4

Codex jobs running at once.

CODEX_MCP_MAX_OUTPUT_CHARS

20000

Longer final messages are truncated (the full text stays in the log folder).

CODEX_MCP_FILE_TOOLS

readwrite with allowed roots, else read

off, read (only workspace_read) or readwrite (also workspace_write). Both stay inside the same folders cwd may use.

CODEX_MCP_SNAPSHOT_MAX_FILES

20000

Workspace snapshot used to list files changed by shell commands. Skips .git, node_modules, build folders. 0 turns it off.

CODEX_MCP_SKIP_GIT_REPO_CHECK

1

Lets Codex work outside git repositories.

CODEX_MCP_LOG_DIR / CODEX_MCP_LOG_RETENTION_DAYS

<tmp>/codex-exec-mcp / 7

Per-job logs (prompt, events, stderr, final message).

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 against allowed roots, client roots and folders you approved; tool arguments can never widen them) 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                      # 59 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Delegates work from MCP clients (like Claude Code) to the Codex CLI, allowing spawning of autonomous Codex subagents for tasks.
      2
      173 PyPI
      177
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets Codex delegate coding and repository work to an installed Claude Code CLI with permission-aware inspect/write access, model and effort selection, resumable and cloud-attached sessions, and durable synchronous or asynchronous jobs.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP-compatible coding agents to execute the local Codex CLI as a coding agent, including code reviews, session resume/fork, and CLI diagnostics.
      9
      11 npm
      MIT