claude-codex-mcp
Drives the official OpenAI Codex CLI (codex exec) to delegate work to Codex on the user's ChatGPT/Codex subscription. Provides tools to run a Codex agent turn in a chosen directory (returning the final message and a session_id to continue the thread), generate images via Codex's built-in image_gen (with count, size, transparent backgrounds and reference images), poll/wait for or cancel asynchronous jobs, list recent jobs, and query the live model catalog to pick a model and reasoning effort per call.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@claude-codex-mcp Ask Codex to review the auth module read-only."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
claude-codex-mcp
Let Claude hand work to OpenAI Codex — code tasks, second opinions and image assets — on the ChatGPT/Codex subscription you already pay for.
claude-codex-mcp is a small MCP server that drives the official Codex CLI (codex exec) on your machine. Claude gets five tools: delegate a task, generate images with Codex's built-in image_gen, poll/cancel jobs, and list models. No OpenAI API key, no token scraping, no third-party service — just the CLI you are already logged into.
It works in Claude Desktop (Chat and Cowork) and Claude Code, and it was built Windows-first.
You: Ask Codex to review the auth module read-only, then fix what you both agree on.
Claude: → codex_task { cwd: "D:\\work\\shop", sandbox: "read-only", model: "gpt-6-astra", reasoning_effort: "xhigh" }
← 3 findings, session_id 01a1… (Claude verifies them, applies the fix, runs the tests)
You: Make 4 transparent gold-coin icons for the HUD.
Claude: → codex_image { prompt: "...", count: 4, transparent: true, out_dir: "D:\\work\\game\\assets\\icons" }
← coin.png, coin-2.png, coin-3.png, coin-4.png + previewsFeatures
Delegation —
codex_taskruns a full Codex agent turn in a folder you choose, returns its final message and asession_idto continue the same Codex thread.Image assets —
codex_imageuses Codex's built-in GPT Image tool, copies results into your project (never overwriting), supports transparent backgrounds and reference images, and returns previews so Claude can check them.Model choice —
codex_modelsreads the live catalog for your account; pick anymodelandreasoning_effort(low…ultra) per call.Never blocks the client — calls wait up to
wait_seconds(default 50 s) and then hand back ajob_id; progress notifications keep long calls alive. Image jobs are serialized so outputs are attributed to the right job.Safe defaults —
workspace-writesandbox (orread-only), network off unless asked, nodanger-full-access. Prompts go over stdin and nothing ever passes through a shell.Zero runtime dependencies — plain Node ≥ 20. Easy to audit: about 1,000 lines in
src/.
Related MCP server: chatgpt-deepseek-bridge
How it works
flowchart LR
C["Claude<br/>Desktop · Cowork · Code"] -- "MCP (stdio)" --> S["claude-codex-mcp"]
S -- "spawn, no shell<br/>prompt on stdin" --> X["codex exec --json"]
X -- "your ChatGPT login" --> O[("OpenAI")]
X -- "JSONL events:<br/>thread id, messages, usage, errors" --> S
X -. "image_gen writes" .-> G["~/.codex/generated_images/<thread>/"]
S -- "copy + preview" --> P["your project's asset folder"]Codex CLI ≥ 0.160 no longer ships codex mcp-server, so this project wraps the supported non-interactive entry point, codex exec, and reads its --json event stream.
Requirements
Node.js 20+
Codex CLI, logged in with your ChatGPT account:
npm i -g @openai/codex(or the Codex desktop app's bundled CLI), thencodex loginA ChatGPT plan that includes Codex. Usage counts against your Codex limits; image generation uses them faster than text.
Install
Option A — Claude Code plugin
/plugin marketplace add aikazu/claude-codex-mcp
/plugin install codex-mcp@aikazuThis adds the MCP server plus a codex-delegation skill that teaches Claude when delegation is worth it and how to brief Codex.
Option B — Claude Desktop / Cowork (and Claude Code)
git clone https://github.com/aikazu/claude-codex-mcp.git
cd claude-codex-mcpWindows (PowerShell):
powershell -ExecutionPolicy Bypass -File .\scripts\install.ps1macOS / Linux:
./scripts/install.shThe installer checks Node and your Codex login, then registers the server as codex in every claude_desktop_config.json it finds (standard and Microsoft Store installs, with a timestamped backup) and in Claude Code (claude mcp add -s user). It pins absolute paths for node and codex, because GUI apps often start MCP servers with a minimal PATH. Fully quit and reopen Claude Desktop afterwards.
Options: -AssetDir <dir> / --asset-dir, -Sandbox read-only / --sandbox, -TaskModel / --task-model, -TaskEffort / --task-effort, -ImageModel / --image-model, -ImageEffort / --image-effort, -DryRun / --dry-run, -Uninstall / --uninstall.
Option C — manual config
{
"mcpServers": {
"codex": {
"command": "C:\\Program Files\\nodejs\\node.exe",
"args": ["C:\\Users\\you\\Tools\\claude-codex-mcp\\src\\cli.mjs"],
"env": { "CODEX_BIN": "C:\\Users\\you\\AppData\\Local\\Programs\\OpenAI\\Codex\\bin\\codex.exe" }
}
}
}claude mcp add codex -s user -- node /path/to/claude-codex-mcp/src/cli.mjsCheck the setup at any time:
node src/cli.mjs --checkTools
Tool | What it does | Key arguments |
| Run a Codex agent turn in |
|
| Generate images with Codex |
|
| Wait for, fetch or cancel a job |
|
| List recent jobs | — |
| Models available to your account + configured default |
|
Results are JSON with status (queued · running · completed · failed · cancelled), final_message, session_id, usage, files (images), changed_files (workspace-write tasks in a git repository: absolute paths whose git status or mtime changed during the run), warnings (e.g. a requested transparent image without alpha), and errors / stderr_tail on failure.
Things to ask Claude
"Show me
codex_models, then ask the strongest one to review this PR's diff, read-only.""Delegate to Codex: add unit tests for
src/payments, then review its diff and run the tests yourself.""Start Codex on the migration in the background and keep working on the UI; check back when it's done."
"Generate a 16:9 key art for the README with Codex, save it to
docs/."
Configuration
Environment variables (set them in the MCP server entry):
Variable | Default | Meaning |
| auto-detect | Path to |
|
| Codex home (auth, config, |
|
| Default sandbox for |
|
| Default |
| Codex |
|
| Codex | Same for |
|
| Default seconds a call waits before returning a |
|
| Concurrent |
|
| Concurrent image jobs (keep 1 for reliable attribution) |
|
| Largest image embedded as a preview |
|
| Previews per result |
Security model
The server is a local stdio process; it opens no ports and stores no credentials. Authentication is entirely the Codex CLI's own login.
Codex runs under its own sandbox:
read-onlyorworkspace-write(writes limited tocwdplusadd_dirs, network off unlessnetwork: true). The bypass/full-access modes are intentionally not exposed. On Windows, delegated runs also turn off the Codex desktop app's browser / computer-use REPL servers (node_repl,cua_repl), which break the sandbox while they run.Arguments are passed as an argv array without a shell; prompts go over stdin.
model,reasoning_effortandsession_idare validated against strict patterns before they reach Codex.Treat Codex output as untrusted input. The bundled skill tells Claude to verify claims and diffs before relaying them.
See SECURITY.md for reporting.
How it compares
There are good projects in this space; each covers part of it. As of October 2026:
Project | Kind | Delegation | Images | Claude Desktop / Cowork | Windows | Notes |
claude-codex-mcp | MCP server | ✓ | ✓ | ✓ | ✓ (primary) | async jobs, model catalog, sandboxed, 0 deps |
Claude Code plugin | ✓ | ✓ | — | not tested | rich set of skills and subagents | |
MCP server | ✓ | — | ✓ | ✓ | ask-codex + brainstorm tools | |
MCP server | ✓ | — | ✓ | — | parallel agents; runs Codex with sandbox bypassed | |
MCP server | — | ✓ | ✓ | ✓ | image-focused, async jobs | |
MCP server | — | ✓ | ✓ | — | calls the ChatGPT backend directly with |
Pick whatever fits; this one aims to be the single, auditable server that covers both jobs everywhere Claude runs.
Troubleshooting
Symptom | Fix |
| Install Codex, or set |
| Run |
Tools don't appear in Claude Desktop | Quit from the tray / menu bar (closing the window is not enough) and reopen. Check the app's MCP logs. |
Calls return | Normal for long runs; Claude polls with |
| Your Codex quota is spent; it resets on your plan's schedule. |
Codex reports | Codex's |
| Codex's sandbox checks the ACLs of everything under |
No image found after a job | Make sure the job wasn't cancelled and that |
Development
npm install # dev tooling only (Biome)
npm test # node:test suite, runs against a fake Codex CLI
npm run lint
node src/cli.mjs --checkThe test suite never calls OpenAI: test/fixtures/fake-codex.mjs mimics codex exec --json, debug models and login status. CI runs it on Windows, macOS and Linux and validates the plugin manifests.
Disclaimer
Independent project, not affiliated with OpenAI or Anthropic. It only automates the official Codex CLI on your own machine with your own account; you remain responsible for complying with the terms of your ChatGPT/Codex plan.
License
MIT © Iqbal Attila
Available Tools
5 toolscodex_imageGenerate images with CodexA
Generate image assets with Codex's built-in image_gen tool (GPT Image), billed to the user's ChatGPT/Codex plan — no API key. Files are copied into out_dir and small previews are returned so you can check them. Use for icons, sprites, illustrations, textures, UI mockups and similar. Supports transparent backgrounds and reference images. Each image typically takes 30-120 s.
Inputs: prompt (required), name, size, count, +7 more.
codex_jobCodex job statusB
Wait for or fetch the result of a codex_task / codex_image job, or cancel it.
Inputs: job_id (required), cancel, wait_seconds.
codex_jobsList Codex jobsBRead-only
List recent jobs started by this server (status, kind, session_id).
Inputs: no named parameters.
codex_modelsList Codex modelsARead-only
List Codex models available to the user's account (slug, description, supported reasoning efforts, default effort) and the configured default from config.toml. Use before choosing model / reasoning_effort.
Inputs: include_hidden.
codex_taskDelegate to CodexADestructive
Delegate a task to OpenAI Codex, running codex exec on this computer with the user's own ChatGPT/Codex subscription. Good for a second opinion or code review, implementing a well-scoped change, refactors, writing tests, or digging through a codebase. Write a self-contained prompt: goal, relevant files, constraints, and what to report back. Codex works in cwd; with sandbox workspace-write it can edit files there. Returns Codex's final message plus a session_id that continues the same Codex session. Runs longer than wait_seconds return a job_id — poll it with codex_job.
Inputs: prompt (required), cwd, model, images, +6 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
codex_task, codex_image, and codex_models target clearly distinct purposes (delegation, image generation, model discovery). The one hazard is codex_job vs codex_jobs, whose near-identical names differ only by number; descriptions do clarify (single-job wait/fetch/cancel vs listing recent jobs), so the overlap is minor rather than fatal.
Every tool shares the predictable `codex_` prefix plus a noun (task, job, image, jobs, models), which reads consistently. The only blemish is the singular/plural pair codex_job/codex_jobs, a small deviation from an otherwise clean scheme.
Five tools is well-scoped for a Codex-delegation server: one per core action (task, image, job polling, job listing, model listing). Each tool earns its place with no redundancy or padding.
The surface covers the full lifecycle: model discovery before choosing, task/image execution, and job wait/fetch/cancel plus listing for async runs. Cancellation being folded into codex_job rather than a dedicated tool is a minor gap an agent can work around.
Related MCP Connectors
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
Authenticated async Opus 5.5 agent with status polling and artifact results.
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables MCP clients like Claude Code to delegate coding tasks to the local Cursor Agent CLI, with persistent per-workspace sessions that resume across calls.12 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables ChatGPT (or any MCP client) to delegate coding tasks to a local Hermes-backed agent with async job management, supporting read-only investigation, implementation, and continuation of sessions via secure MCP tunnel.1MIT
- AlicenseAqualityBmaintenanceEnables MCP clients such as Claude Code, Codex, and Cursor to dispatch background subagent jobs to the Antigravity IDE's local agent engine and collect results asynchronously. Jobs run through the IDE's authenticated session without an API key, with optional Gemini REST fallback and on-disk job history.63MIT
- AlicenseNot gradedqualityAmaintenanceConnects MCP clients such as Claude, Cursor, and VS Code to an OpenCode server's headless API, enabling users to ask questions, delegate and run coding tasks, monitor background jobs, answer prompts and permission requests, and review resulting changes across multiple projects. Sessions accept absolute server-side project directories, support both blocking and asynchronous workflows, and expose persisted job records for recovering or cancelling work.23,789 npmMIT