Codex Imagegen MCP README

Codex ImageGen MCP — a 1930s travel-poster illustration: an enormous empty picture frame stands on a desert plain and frames a rising sun behind a peak, while a small train runs along a railway toward it

Codex's image generation, in every coding agent.
Generate and edit images from opencode, Claude Code, Codex, Cursor, VS Code, Gemini CLI and 20 more tools.
It runs on the ChatGPT plan you already pay for, so there's no API key and no per-image bill.

Quick start · See it work · Tools · Sign-in · Clients · All docs

What it does

Your ChatGPT plan, not an API bill Sign in once with ChatGPT, or reuse the sign-in Codex or opencode already has. Every image counts against the plan you already pay for.	One installer, 25+ tools `npx -y codex-imagegen-mcp install` finds your coding tools, shows every file it will touch, and edits only its own entry, keeping your comments.	Real transparent PNGs Ask for `background: "transparent"` and get genuine alpha, checked on every file. A local chroma-key tool handles the rest.
Any canvas shape Eleven aspect ratios from 21:9 to 9:21, and up to four variants of a prompt in parallel.	Saves into your project, safely Paths resolve to your workspace. An existing file is never overwritten; you get `hero-2.png` instead.	Codex's own playbook Ships the Codex app's `imagegen` skill as `imagegen-mcp`, adapted to these tools: prompt structure, edit invariants, save rules.

See it work

Two real opencode sessions in a scratch project. The images are exactly what came back:

Three real outputs: a transparent cartoon cactus sticker, the same sticker edited to wear a straw hat, and a 16:9 photographic hero of a cactus shop at sunset

You: I need a sticker-style illustration of a cute cartoon cactus with a transparent background for this project. Save it as assets/cactus-sticker.png.

opencode · openai/gpt-5.5 loads the skill → imagegen_generate_image with background: "transparent" → "Saved assets/cactus-sticker.png, 1254×1254 PNG with a transparent background."

You: Make a 16:9 hero banner for the Cactus Shop landing page, and a variant of the sticker where the cactus wears a tiny straw hat. Keep everything else identical.

opencode · github-copilot/claude-sonnet-5 → imagegen_auth_status → imagegen_generate_image (aspect_ratio: "16:9") and imagegen_edit_image (images: ["assets/cactus-sticker.png"]) in parallel → both saved, the edit with "transparent background (alpha verified)".

One prompt, three canvases. aspect_ratio doesn't crop. The service composes a new picture for each shape:

The same travel-poster prompt of a train crossing a trestle bridge, generated at 1:1 (1254×1254), 16:9 (1672×941) and 9:16 (941×1672)

A green screen becomes alpha on your machine. remove_background keys out a flat backdrop locally, with no network call and no quota:

A striped hot-air balloon generated on a flat green backdrop, and the same balloon cut out onto a transparent checkerboard

[!TIP] Every image in this repository was made with codex-imagegen-mcp itself. That covers the posters, the badges, the logo and the examples; the installer screenshots are real terminal output. The prompts and the art-direction record are in docs/assets.

Quick start

[!NOTE] You need Node.js 22+ and a ChatGPT plan that includes Codex (Plus, Pro, Business, Enterprise, Edu…). Codex image generation isn't available on the Free plan.

1 · Run the installer. npx fetches the latest release, so there's nothing to install first. The installer finds the coding tools on this machine, shows exactly which files it will create or change, and writes nothing until you confirm. Each config keeps its comments and formatting.

Terminal

npx -y codex-imagegen-mcp install

The interactive installer: it found 10 of 25 supported tools and lists them grouped as terminal agents and editors, with the detected ones pre-selected

The configs it writes start the server through npx as well; npm downloads it on first use and caches it. The installer also runs without questions, for scripts and dotfiles:

Terminal

npx -y codex-imagegen-mcp install opencode cursor claude-code   # named tools (see --list)
npx -y codex-imagegen-mcp install --all --dry-run               # every detected tool, preview only

Prefer a global install, the GitHub release, or a source checkout?

A global install gives you the short codex-imagegen-mcp command. The installer then writes an absolute Node path instead of npx, which starts faster and doesn't depend on npx. That suits GUI apps like Claude Desktop and Cursor best:

Terminal

npm install --global codex-imagegen-mcp
codex-imagegen-mcp install

The same package is attached to every GitHub release with a signed build-provenance attestation:

Terminal

npm install --global https://github.com/ShalomObongo/codex-imagegen-mcp/releases/latest/download/codex-imagegen-mcp.tgz

From source:

bash

git clone https://github.com/ShalomObongo/codex-imagegen-mcp.git && cd codex-imagegen-mcp
npm ci && npm run build
npm link                                  # puts `codex-imagegen-mcp` on your PATH

2 · Sign in with ChatGPT. The installer offers this at the end. Skip it if Codex or opencode is already signed in with ChatGPT.

Terminal

npx -y codex-imagegen-mcp login           # opens the browser; use --device on a headless machine

3 · Check, then ask for pictures

Terminal

npx -y codex-imagegen-mcp doctor          # Node, credentials, quota, and every tool it's installed in

text

you › Make a 16:9 hero image of a lighthouse at dusk and save it to assets/hero.png

[!TIP] From here on, commands use the short codex-imagegen-mcp from a global install. Without one, run them through npx the same way, for example npx -y codex-imagegen-mcp status.

How it works

mermaid

sequenceDiagram
    autonumber
    participant A as Your agent<br/>(opencode, Claude Code…)
    participant M as imagegen MCP server<br/>(local · stdio)
    participant O as auth.openai.com
    participant C as chatgpt.com<br/>/backend-api/codex
    A->>M: generate_image {prompt, aspect_ratio, background}
    M->>M: pick credentials: own sign-in → Codex → opencode
    opt token expires within 5 minutes
        M->>O: refresh (under a cross-process lock)
        O-->>M: new access token + rotated refresh token
    end
    M->>C: POST /images/generations · Bearer token · ChatGPT-Account-ID
    loop every 5 s while the image renders
        M-->>A: progress notification (keeps the client's timeout alive)
    end
    C-->>M: PNG + usage headers
    M->>M: save without overwriting · verify alpha · build preview
    M-->>A: path, size, background + a 1024 px preview

It sends the same request as the image tool built into the Codex app, byte for byte. As OpenAI improves Codex's image model on the server, this server gets the same upgrade. How that was reverse-engineered →

Signing in

You already have…	What happens
Codex (CLI or desktop app) signed in with ChatGPT	Works immediately. The server borrows `~/.codex/auth.json` read-only.
opencode signed in with OpenAI → ChatGPT Plus/Pro	Works immediately. It borrows `~/.local/share/opencode/auth.json` read-only.
Neither, or you want an independent sign-in	Run `codex-imagegen-mcp login`, or ask your agent to call the `sign_in` tool.

bash

codex-imagegen-mcp login            # browser → sign in → "You're signed in to Codex ImageGen MCP"
codex-imagegen-mcp login --device   # SSH/headless: enter a code at auth.openai.com/codex/device
codex-imagegen-mcp status           # account, plan, credential source and usage windows
codex-imagegen-mcp logout           # remove and revoke this tool's own sign-in

[!IMPORTANT] OpenAI refresh tokens are single-use. Borrowed sign-ins are therefore never refreshed or modified, so this server can't sign you out of Codex or opencode. Its own tokens are stored 0600 and refreshed under a lock shared by every server process. Authentication in depth →

Tools

Tool	What it does	Key parameters
`generate_image`	A new image from a prompt	`prompt` · `aspect_ratio` · `background` · `n` · `output_path`
`edit_image`	Edit images, or generate from 1–5 references	`images` · `prompt` · same options
`remove_background`	Cut a flat backdrop out locally (no quota)	`input_path` · `key_color` (auto) · `output_path`
`auth_status`	Sign-in, plan, credential source, usage windows	`check_usage`
`sign_in`	Start a ChatGPT sign-in and return a link or code for you	`method` (`browser` · `device`)

The server also exposes the resources imagegen://history, imagegen://images/{id} and imagegen://skill/*, and the prompts generate and edit. In opencode the prompts appear as /imagegen:generate and /imagegen:edit. Full reference →

From the terminal

The CLI uses the same engine as the MCP tools:

bash

codex-imagegen-mcp generate "a watercolor fox in a snowy forest" -a 16:9 -o art/fox.png
codex-imagegen-mcp generate "Image 1: add a tiny straw hat; keep everything else" \
  -i assets/cactus.png -b transparent -o assets/cactus-hat.png
codex-imagegen-mcp remove-bg sprite-on-green.png -o sprite.png
codex-imagegen-mcp config zed              # print a tool's config snippet to add by hand

Supported tools


Terminal agents	OpenCode · Claude Code · Codex · Gemini CLI · GitHub Copilot CLI · Amp · Goose · Factory Droid · Qwen Code · JetBrains Junie · Augment (Auggie)
Editors & IDEs	Cursor · VS Code, Insiders and VSCodium · Devin Desktop (formerly Windsurf) · Zed · Kiro · Google Antigravity · Visual Studio (Windows)
Desktop apps	Claude Desktop, with the skill as an uploadable zip
Editor extensions	Cline · Zoo Code / Roo Code · Kilo Code
By hand	JetBrains AI Assistant (the installer prints the JSON to paste) · anything else: `codex-imagegen-mcp config <tool>`

Each tool gets its own config format, timeout field and skill folder. install --list shows which ones are on your machine. Files, timeouts and skill folders per tool →

Documentation

Tools Every tool, parameter, result field, resource and error.	Authentication PKCE and device-code sign-in, token rotation, borrowing, security.	Clients The installer, and the 25+ supported tools: files, timeouts, skills.
Backend How Codex's image generation really works: extracted and measured.

FAQ

Does it cost anything?

No extra money. Images come out of your ChatGPT plan's Codex usage limits, the same as images you make in the Codex app. codex-imagegen-mcp status (or the auth_status tool) shows the 5-hour and weekly windows, and checking them uses no quota.

Is the output the same as Codex's built-in image tool?

Yes. The endpoint, request body and auth headers are identical to the ones the Codex desktop app sends. The service picks the model, resolution and quality itself, for Codex and for this server alike.

Can I choose gpt-image-2.5, an exact size or a quality level?

Not with a ChatGPT sign-in. The service ignores model, size, quality and n. That was measured, including requests for the newer gpt-image-2.5-sunburst and -flare models, and the tools deliberately don't pretend otherwise. Choose the shape with aspect_ratio; for exact pixels, resize or crop afterwards. Selecting a model explicitly requires the billed OpenAI Platform API, which is out of scope by design. The measurements →

Where do images go?

They go to output_path, relative to your workspace, when you give one. Otherwise they land in the image library at ~/.local/share/codex-imagegen-mcp/images/<date>/. Every file is also recorded in imagegen://history. Existing files are never replaced unless you pass overwrite: true.

Will it sign me out of Codex or opencode?

No. Borrowed sign-ins are read-only: they're used while their access token is valid and are never refreshed or written. Its own sign-in (login) is independent. Why that matters →

Is this official?

No. It's an unofficial integration that uses the same public OAuth client and internal ChatGPT endpoints as the Codex CLI, as opencode's ChatGPT sign-in also does. Those interfaces are undocumented and may change. Use it within OpenAI's Terms of Use.

Is the npm package really built from this repository?

Yes, and you can check. The release pipeline builds each release once, from a tagged commit on main, and tests it on Linux, macOS and Windows. It then publishes it through npm's trusted publishing, so no token is involved. The npm package and the GitHub release tarball are the same file, and both carry signed provenance that names the tag and commit:

Terminal

npm audit signatures        # in a project that depends on codex-imagegen-mcp
gh attestation verify codex-imagegen-mcp-X.Y.Z.tgz --repo ShalomObongo/codex-imagegen-mcp

Release integrity →

Configuration

Environment variables

Variable	Default	Purpose
`CODEX_IMAGEGEN_HOME`	`~/.local/share/codex-imagegen-mcp`	Credentials, history, logs and the default image library
`CODEX_IMAGEGEN_OUTPUT_DIR`	`$CODEX_IMAGEGEN_HOME/images`	Where images go when no `output_path` is given
`CODEX_IMAGEGEN_CREDENTIALS`	`auto`	`auto` (own → Codex → opencode), or pin `own`, `codex` or `opencode`
`CODEX_IMAGEGEN_TIMEOUT_MS`	`300000`	Per-request timeout for the image service
`CODEX_IMAGEGEN_LOG_LEVEL`	`info`	`debug`, `info`, `warn`, `error` or `silent`; the log is `$CODEX_IMAGEGEN_HOME/server.log`
`CODEX_IMAGEGEN_NO_BROWSER`	unset	Never open a browser automatically
`CODEX_HOME`	`~/.codex`	Where to look for a Codex sign-in
`CODEX_IMAGEGEN_ORIGINATOR`	`codex-imagegen-mcp`	The `originator` identifying this client to OpenAI

Test-only overrides: CODEX_IMAGEGEN_BASE_URL, CODEX_IMAGEGEN_USAGE_URL, CODEX_IMAGEGEN_AUTH_ISSUER, CODEX_IMAGEGEN_CLIENT_ID, CODEX_IMAGEGEN_OPENCODE_AUTH_FILE.

Troubleshooting

Start with codex-imagegen-mcp doctor. It checks Node, the data directory, credentials, backend reachability and quota, the sign-in ports, every tool that has imagegen configured, and the skill copies.

Common problems

Symptom	Fix
`Not signed in`	`codex-imagegen-mcp login` (or `--device`), or open Codex/opencode once so their sign-in refreshes
`usage limit … resets in …`	Wait for the reset; `status` shows the windows
`ports 1455 and 1457 are busy`	Another Codex or opencode login is waiting. Finish it, or use `login --device`
`Device-code sign-in is not enabled`	ChatGPT → Settings → Security → allow device code authorization for Codex
Tools missing in a client	Run `doctor`, re-run `install <tool>`, then restart the tool (`install --list` shows the ids)
`conflict` in the installer	Another server already uses the name `imagegen`: pass `--name`, or `--force` to replace it
An opaque result despite `transparent`	Retry, or generate on a flat `#00FF00` backdrop and run `remove_background`
`npm error ETARGET` · `No matching version found`	The release is minutes old: npm takes a minute or two to serve a new version to installs. Wait and retry; `npx --prefer-online -y codex-imagegen-mcp install` also skips npm's local metadata cache

Still stuck? See getting help.

Contributing

Bug reports, docs fixes, support for more clients and backend measurements are welcome. Start with CONTRIBUTING.md; security issues go through SECURITY.md, never public issues. Every release is listed in the changelog.

Changelog · Contributing · Security · Code of Conduct · Support
_{Unofficial; not affiliated with or endorsed by OpenAI. Usage counts against your ChatGPT plan and is subject to OpenAI's Terms of Use.

Generated images carry OpenAI's C2PA provenance metadata. Apache-2.0; the bundled skill is adapted from OpenAI Codex (Apache-2.0), see NOTICE.}