codex-image-mcp

No API key. No credits. No third-party service holding your prompts. This is an MCP server that drives the Codex CLI already bundled inside ChatGPT.app, which authenticates from your own ~/.codex/auth.json and calls OpenAI's built-in gpt-image-2. Every image on this page, banner included, came out of the tool while I was building it.

Why I built it

I wanted Claude to make images for me. Every option was wrong. The hosted MCP servers — Pixa, ImagineArt, Claude Imagine — are someone else's service with a credit tier attached. The OpenAI-key servers bill you per image for a model your subscription already covers. Local diffusion on a 16 GB M1 Pro is slow and nowhere near gpt-image-2 on quality.

Then I noticed my ChatGPT app ships a full Codex binary, that Codex has image generation switched on by default, and that it signs in as me. The bridge turned out to be one command. Getting that command to behave took considerably longer, and the rest of this README is what went wrong along the way.

Related MCP server: GPTImage

Install

You need the ChatGPT desktop app and a logged-in Codex session. Then:

git clone https://github.com/Equallogic/codex-image-mcp.git
cd codex-image-mcp && npm install
claude mcp add --scope user codex-image -- node "$(pwd)/server.js"

Restart Claude Code. Five tools appear:

generate_image(prompt, output_path, [reference_images], [transparent_background])
edit_image(image_path, instruction, output_path, [reference_images], [transparent_background])
second_opinion(question, [files], [cwd])
review_code(repo_path, [base | commit], [instructions])
run_skill(skill, task, output_dir, [input_files])

The image tools write the file and hand back the path, format, dimensions, elapsed time and tokens spent. Roughly 45 seconds an image. edit_image never overwrites its source, and leaves the source's transparency alone unless told otherwise.

second_opinion and review_code run GPT-6 Astra at high effort in a read-only sandbox, so another model family can check Claude's work without being able to change it. review_code reviews uncommitted work by default.

run_skill hands a task to one of your own Codex skills, in ~/.codex/skills or ~/.agents/skills, so a skill built around the image model (packaging systems, lifestyle shots, brand boards) is one call away from Claude. Codex may write only inside output_dir, and the plugins that bring computer use stay off. You get Codex's report plus every file it actually wrote, read back from disk.

What I learned making it reliable

This is the part worth reading, because all three of these cost me real money to find out.

Phrasing decides whether you get an image at all. Ask for "Generate an image: X. Just generate the image." and Codex replies with the image tool's own prompt-writing guidance instead of calling it. Seventy-eight seconds, 22,739 tokens, no picture. The server sends an imperative that names the destination file instead, and that has worked every time since.

Codex reports success whether or not a file appeared. It prints "Created with built-in ImageGen" and a plausible path. That means nothing. So the server ignores the prose entirely and goes to the disk: magic bytes to confirm it is an image at all, the PNG header for dimensions, and an mtime guard so that a stale file already sitting at the target path cannot quietly pass itself off as a fresh result. No image, no success. You get an error.

The overhead was never the tool. The image_gen schema is 435 tokens. What costs you is that an image request makes the agent read 17,763 bytes of imagegen/SKILL.md first, then take several more passes to generate, copy and verify. Suppressing that skill removes the read and a whole model pass — 80,049 aggregate input tokens down to 61,197. That single override is worth more than every other flag combined.

Do not trust the token count Codex prints

It is cache-discounted. Identical requests were measured taking anywhere from 0 to 17,664 cached tokens, so the figure moves with cache warmth and can go up when a change makes the prompt smaller. I chased that number for an afternoon. Every conclusion I drew from it was wrong, including a confident 24% improvement that never existed.

Parse --json and sum input_tokens across the turn.completed events instead. This server does, and reports input, cached and billed separately on every call.

Two more traps in codex-cli 0.154.0-alpha.6.2. -c 'plugins."x".enabled=false' is accepted, even under --strict-config, and silently does nothing — --ignore-user-config is the only isolation that works. And model_reasoning_effort is not ignored in exec, whatever the input token counts suggest: low and high are identical on input because effort is a request parameter rather than prompt text.

Cost

About 8,000 to 12,000 billed tokens an image, out of roughly 50,000 to 75,000 aggregate input, most of which comes back as a cache hit. That is subscription quota, not dollars.

There is no lighter route on a subscription. codex exec always runs the full agent, and Codex CLI has no command that calls image_gen on its own. If you want cheap single images and you have API billing, use /v1/images/generations directly and skip all of this.

What it will not do

Edits are instruction-driven over the whole image. Codex's image tool takes no mask, so describe the region in words.

Transparent backgrounds work as of codex-cli 0.159.2, but the server does not take Codex's word for it: it decodes the PNG and fails unless pixels are actually clear. Expect a faint colour fringe on hard edges.

It is also the wrong tool for icons and logotype. Draw those as SVG.

Configuration

macOS only, because the Codex binary lives inside the Mac app.

Licence

MIT.