Codex / OpenAI Image

codex-openai-image-mcp

An MCP server that lets Claude (and any other MCP client) generate images, edit them, and make matching sets, then look at the result and keep going.

It works with two image backends:

• Codex CLI: uses the ChatGPT plan you already have through the Codex CLI. No API key, no per-image bill.
• OpenAI Images API: uses an OPENAI_API_KEY, for people without Codex.

Not affiliated with or endorsed by OpenAI. "OpenAI" and "Codex" are trademarks of OpenAI.

Both examples are real, unretouched output from the Codex backend.

What makes it different

• Matching sets. generate_set makes several different images that share one style, each saved under its own name.
• Two backends, one interface. Switch between Codex and the OpenAI API with one setting.
• Made for an agent loop. Every call returns small previews that Claude can see, reports progress during long runs, can be cancelled, and writes a .json sidecar with the prompt and settings next to each image.
• Careful with your files. It writes only inside its output folder, never overwrites an existing file, never changes the image you edit, and runs Codex read-only in an empty temporary folder.

Quick start

You need Node.js 20.3 or newer, plus one of:

• the [Codex CLI](https://github.com/openai/codex), signed in (codex login) with a ChatGPT plan that includes Codex image generation, or
• an OpenAI API key with credits.

Claude Code

# Codex backend (your ChatGPT plan)

claude mcp add images -e IMAGEGEN_PROVIDER=codex-cli -- npx -y codex-openai-image-mcp

or the OpenAI API

claude mcp add images -e IMAGEGEN_PROVIDER=openai-api -e OPENAI_API_KEY=sk-... -- npx -y codex-openai-image-mcp

Claude Desktop, Cursor and other clients

Add this to the client's MCP config (for Claude Desktop, claude_desktop_config.json):

{

"mcpServers": { "images": { "command": "npx", "args": ["-y", "codex-openai-image-mcp"], "env": { "IMAGEGEN_PROVIDER": "codex-cli" } } } }

For the API backend use "IMAGEGEN_PROVIDER": "openai-api" and add "OPENAI_API_KEY".

Then just ask:

• *"Make a watercolour fox for my blog header, 1536x864."*
• *"Edit photo.png so it looks like a sunset."*
• *"Make 5 matching app icons: home, search, profile, settings, bell."*

Images are saved in ./generated-images in the folder the client was started from.

Tools

generate_image

edit_image

generate_set

All tools crop and resize the result to exactly the size you ask for, and return the saved paths with a 512 px preview of each image.

Backends

mock draws placeholder images, for trying the server out and for tests.

Codex backend. Each call runs codex exec --json --skip-git-repo-check --sandbox read-only --cd [--image= …] -- - with a prompt that asks Codex to call its built-in image_gen tool and nothing else. The server reads the session id from Codex's JSON events and collects the images from $CODEX_HOME/generated_images/ /. Codex never gets write access or sees your project beyond the images you pass it. Cancelling the request, or hitting the timeout, stops Codex. Check OpenAI's terms for scripted use of the Codex CLI with your plan.

OpenAI backend. Uses the official openai SDK. The default model is gpt-image-2.5-sunburst; set IMAGEGEN_OPENAI_MODEL=gpt-image-2.5-flare for faster results. Sizes are rounded to ones the API accepts, then resized to yours. This backend is covered by automated tests against a mocked client; it has not yet had a full live test.

Settings

Files and safety

• Output is written only inside IMAGEGEN_OUT_DIR. Absolute paths, .. and symlinks that lead outside are rejected.
• Input images (to edit, or as references) must be inside IMAGEGEN_READ_ROOT.
• Existing files are never overwritten: a new file gets -2, -3, … instead.
• Each image gets a .json sidecar with the prompt, backend, model, size, inputs and time.
• API keys are read from the environment only and never logged or written to sidecars.
• IMAGEGEN_MAX_PER_CALL caps how many images one call can make.

Images are AI-generated. You are responsible for how you use them, including platform rules on AI-generated content, and for not imitating real people or brands.

Development

git clone https://github.com/meet30997/codex-openai-image-mcp.git

cd codex-openai-image-mcp npm install npm run build npm test # unit and end-to-end tests; no network or API key needed npm run inspect # try the tools in the MCP Inspector

To run a local build from Claude Code:

claude mcp add images -e IMAGEGEN_PROVIDER=codex-cli -- node /path/to/codex-openai-image-mcp/dist/index.js

The tests run the Codex backend against a stand-in script (test/fixtures/fake-codex.mjs) and the OpenAI backend against a fake client, so they are free and quick. PLAN.md has the design notes and roadmap. Issues and pull requests are welcome.

License

MIT