x51xxx/codex-mcp-tool

MCP server connecting Claude/Cursor to Codex CLI. Enables code analysis via @ file references, multi-turn conversations, sandboxed edits, and structured change mode.
Features
- **File Analysis** — Reference files with @src/, @package.json syntax
- **Multi-Turn Sessions** — Conversation continuity with workspace isolation
- **Native Resume** — Uses codex resume for context preservation (CLI v0.36.0+)
- **Local OSS Models** — Run with Ollama or LM Studio via localProvider
- **Web Search** — Research capabilities with search: true
- **Sandbox Mode** — Safe automation with explicit sandbox and approval policies
- **Change Mode** — Structured OLD/NEW patch output for refactoring
- **Brainstorming** — SCAMPER, design-thinking, lateral thinking frameworks
- **Health Diagnostics** — CLI version, features, and session monitoring
- **Cross-Platform** — Windows, macOS, Linux fully supported
Quick Start
**Prerequisites:** Node.js 18+, Codex CLI installed and authenticated.
Configuration
**Config locations:** macOS: ~/Library/Application Support/Claude/claude_desktop_config.json | Windows: %APPDATA%\Claude\claude_desktop_config.json
Usage Examples
Tools
| Tool | Description |
| ---------------- | ------------------------------------------------------------------- |
| ask-codex | Execute Codex CLI with files, models, sessions, and safety controls |
| batch-codex | Run multiple atomic Codex tasks sequentially or concurrently |
| review-changes | Run the native non-interactive Codex review command |
| do-act | Execute, verify with a shell command, and retry fixes |
| image-gen | Generate or edit images with Codex's built-in image_gen tool |
| brainstorm | Generate ideas with structured creative frameworks |
| list-sessions | View, delete, or clear MCP conversation mappings |
| list-skills | List skills visible from the selected workspace |
| health | Diagnose CLI installation, version, features, and sessions |
| fetch-chunk | Retrieve a chunk from cached change-mode output |
| ping | Test the MCP connection |
| help | Return current codex --help output |
| version | Report Codex CLI, Node.js, platform, and package versions |
| timeout-test | Exercise keepalive and timeout behavior |
Image generation
image-gen drives Codex's built-in image_gen tool, so it uses your ChatGPT
login and needs no OPENAI_API_KEY. That tool only accepts a prompt and
reference image paths: Codex picks the image model and pixel size, and there
are no size, quality, format or mask arguments. image-gen therefore puts all
steering into a structured prompt (use case, asset type, style, composition,
exact text, reference roles, edit invariants, aspect ratio, presets) and tells
the Codex host model to relay it instead of improvising.
Images are saved by Codex under $CODEX_HOME/generated_images/ / and
copied to outputPath when given; an existing file is kept and the copy is
written as a -v2 sibling unless overwrite: true. The result reports each
file's dimensions and alpha channel, so a transparentBackground request that
came back opaque is flagged.
Models
By default the model parameter is **omitted** and Codex CLI applies the
default model from your ~/.codex/config.toml (for example model = "gpt-6.1-sol").
Pass model only when you need to override the configured default for a
single call. Reasoning depth is calibrated per tool:
- ask-codex — uses the Codex CLI default reasoning (medium). Increase it only when the task needs more planning or checking.
- brainstorm, do-act, review-changes — default reasoningEffort: "high" (creative ideation, act-check-fix loops, and code review benefit from deeper reasoning).