Skip to main content
Glama

What it does

Related MCP server: codex-imagegen-mcp

See it work

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

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:

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

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 indocs/assets.

Quick start

NOTE

You needNode.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.

npx -y codex-imagegen-mcp install

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:

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

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:

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:

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

From source:

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.

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

3 · Check, then ask for pictures

npx -y codex-imagegen-mcp doctor          # Node, credentials, quota, and every tool it's installed in
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 shortcodex-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

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.

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 aresingle-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:

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

FAQ

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.

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.

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 →

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.

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 →

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.

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:

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

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.

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.


Available Tools

5 tools
auth_statusSign-in and quota statusA
Read-onlyIdempotent

Show whether image generation is signed in, which ChatGPT account/plan and credential source is used, and the current usage-limit windows. Costs no image quota. Call this when a tool reports an auth or quota problem, or after sign_in.

Inputs: check_usage.

edit_imageEdit imageA

Edit or transform existing images, or create a new image guided by reference images, using the user's ChatGPT plan (no API key). Pass 1-5 images; refer to them in the prompt as Image 1, Image 2… (Image 1 is the primary edit target). State exactly what must change AND what must stay unchanged. Good for background replacement or removal, object removal/insertion, restyling, relighting, text localization, compositing and sketch-to-render. The input file is never modified; the result is saved as a new file.

Inputs: images (required), prompt (required), n, overwrite, +5 more. Returns: images, prompt, failures, warnings, +1 more

generate_imageGenerate imageA

Generate a new raster image (photo, illustration, texture, sprite, mockup, icon, product shot…) from a text prompt, using the user's ChatGPT plan — the same image service as OpenAI Codex's built-in image tool, no API key. Saves the full-resolution file and returns its path plus a preview. The service chooses resolution and quality; steer orientation with aspect_ratio or in the prompt. Use background="transparent" for assets that need real alpha. Typically takes 15-60 s.

Inputs: prompt (required), n, overwrite, background, +4 more. Returns: images, prompt, failures, warnings, +1 more

remove_backgroundRemove flat background (chroma key)A
Idempotent

Locally remove a flat, solid-color background from a PNG/JPEG and save a transparent PNG — no network, no quota. Use for images with a uniform backdrop (e.g. generated "on a flat pure #00ff00 background"), or to clean up a cutout. The key color is sampled from the image border unless key_color is given. Prefer background="transparent" on generate_image/edit_image when creating new assets.

Inputs: input_path (required), despill, key_color, overwrite, +8 more.

sign_inSign in with ChatGPTA
Idempotent

Start signing this image server in to the user's ChatGPT account (required once before generating, unless an existing Codex/opencode ChatGPT sign-in is detected). Returns a link (browser method) or a code (device method) that the USER must open or enter — relay it verbatim. Sign-in completes in the background; afterwards call auth_status to confirm.

Inputs: force, method, open_browser.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a unique purpose: generate_image creates new images, edit_image modifies existing ones, remove_background handles a specific transformation, auth_status checks state, and sign_in handles authentication. There is no overlap or ambiguity; an agent can reliably choose the right tool for the task.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern: generate_image, edit_image, remove_background, auth_status, sign_in. Even though auth_status is more of a state query, it fits the pattern well. The naming is predictable and easy to infer.

    Tool Count5/5

    Five tools is ideal for an image generation server. It covers creation, editing, a specific utility, plus auth and status checks—everything needed without unnecessary surface. The scope is clear and each tool earns its place.

    Completeness5/5

    The tool surface fully covers the domain: generation, editing, background removal, and authentication. There are no missing operations that would cause dead ends; users can create, modify, and manage sessions seamlessly. The lifecycle is complete for this server's intended functionality.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers