![codex-image-mcp — image generation in Claude Code, paid for by the ChatGPT subscription you already have](samples/social-preview.png)

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

## Install

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

```bash
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

| variable | default |
|---|---|
| `CODEX_BIN` | `/Applications/ChatGPT.app/Contents/Resources/codex-cli/bin/codex`, then the pre-October `Resources/codex` |
| `CODEX_HOME` | `~/.codex` |
| `CODEX_IMAGE_MODEL` | `gpt-6.1-sol` (the agent, not the image model) |
| `CODEX_IMAGE_TIMEOUT_MS` | `300000` |
| `CODEX_REVIEW_MODEL` | `gpt-6-astra` |
| `CODEX_REVIEW_EFFORT` | `high` |
| `CODEX_REVIEW_TIMEOUT_MS` | `900000` |
| `CODEX_SKILL_EFFORT` | `medium` |
| `CODEX_SKILL_TIMEOUT_MS` | `1800000` |

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

## Licence

MIT.