codex-img
Provides image generation and editing tools backed by OpenAI's ChatGPT/Codex image endpoint (the same one used by Codex CLI's built-in imagegen skill). Agents can call generate_image to create an image from a text prompt and edit_image to modify 1–5 reference images with a text instruction, with options for transparent background, size, quality, model id, and output path. It reuses an existing codex login (ChatGPT subscription) credential from ~/.codex/auth.json, refreshing tokens as needed, so the ChatGPT plan's image-generation quota can be used from any MCP client instead of only Codex. Note that on this subscription channel the backend ignores the requested model and size and returns whatever GPT-Image it serves.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
codex-img-cli
Give any agent GPT-Image generation, by reusing the Codex / ChatGPT subscription you already pay for.
Codex CLI ships an imagegen skill — but it lives inside the agent, so nothing
else can reach it. Claude Code, MiniMax Code, OpenCode, Cursor, your own
scripts… none of them can turn your ChatGPT plan into an image.
codex-img-cli extracts the exact same endpoint into a standalone CLI and an
MCP stdio server. Point any MCP client at it and "draw me a picture" becomes
a tool call.

Zero runtime dependencies · Node.js ≥ 20 · credentials never leave your machine
English | 简体中文
Why
Codex | codex-img-cli | |
Who can call it | Codex only | any agent, any script |
Interface | sealed inside the agent | CLI + MCP stdio server |
Extra setup | — |
|
Credentials | managed by Codex | read from |
Dependencies | — | none |
Related MCP server: Codex ImageGen MCP
How it works
The request shape is taken from the openai/codex source
(codex-rs/ext/image-generation/src/):
POST https://chatgpt.com/backend-api/codex/images/generations
POST https://chatgpt.com/backend-api/codex/images/edits
Authorization: Bearer <tokens.access_token>
ChatGPT-Account-ID: <tokens.account_id>
Content-Type: application/json
{ "model": "gpt-image-2", "prompt": "...", "background": "opaque",
"quality": "auto", "size": "auto" }Authentication reads ~/.codex/auth.json — the file codex login writes. Your
OPENAI_API_KEY is never touched. When the access token is about to expire,
the refresh_token from the same file is exchanged for a fresh one and written
back atomically (temp file + rename), so Codex CLI and this tool can share one
login.
Signing in
Already have codex login on this machine? Nothing to do — the tool picks
up ~/.codex/auth.json and refreshes it for you.
No Codex login? Sign in with this tool instead:
codex-img login # browser flow
codex-img login --device # device code, for SSH / containers / headless boxesThe credentials are written to <package>/.codex-img/auth.json — inside the
package's own install directory. Two consequences:
Uninstalling the package removes the credentials with it. No token is left on the machine. npm 11 has no uninstall lifecycle hook at all (its arborist does not implement
preuninstall/postuninstall), so the layout is what makes that guarantee real rather than a promise.Reinstalling the package — or switching Node versions when it is installed globally — means signing in again. Set
CODEX_IMG_HOMEto keep the credentials somewhere else if you would rather.
The Codex login in ~/.codex is never overwritten. When both exist, the
credentials managed here take precedence; codex-img logout removes them and
falls back to the Codex login.
codex-img logout # remove the credentials this tool manages
codex-img auth # show which store is in useInstall
git clone https://github.com/xurunxin/codex-img-cli.git
cd codex-img-cli
npm link # puts `codex-img` on your PATH
npm test # 20 unit tests, no network access requiredPrerequisite: run codex login on this machine, with an account that has a
ChatGPT subscription.
Prefer not to install it? node bin/codex-img.mjs ... works exactly the same.
npm link writes the shim into the npm global directory. Under nvm-windows that
is the version directory (…\nvm\installs\<version>\), which is not on PATH
and disappears when you switch Node versions. Drop a small wrapper into a
directory that is on PATH:
@echo off
setlocal
set "CODEX_IMG_ENTRY=<repo>\bin\codex-img.mjs"
set "CODEX_IMG_NODE=%LOCALAPPDATA%\Author Software\nvm\.nodejs\node.exe"
if not exist "%CODEX_IMG_NODE%" set "CODEX_IMG_NODE=node"
"%CODEX_IMG_NODE%" "%CODEX_IMG_ENTRY%" %*
exit /b %errorlevel%Save it as %USERPROFILE%\.local\bin\codex-img.cmd, then check with
where codex-img.
Quick start
codex-img auth # check the login — offline, no quota
codex-img gen --prompt "a cozy alpine cabin at dawn" --out cabin.png
codex-img edit --image cabin.png \
--prompt "replace the background with a warm sunset, keep the cabin unchanged" \
--out sunset.pngCLI reference
Command | What it does |
| Show credential status — no network request |
| Sign in with a ChatGPT subscription (no Codex login needed) |
| Remove the credentials this tool manages |
| Generate an image from a text prompt |
| Edit existing image(s) with a text instruction |
| Probe which model ids the endpoint actually honours |
| Run as an MCP stdio server |
Common options:
Option | Description |
| Output path (default |
| Shorthand for |
|
|
|
|
| e.g. |
| Model id placed in the request body (see below) |
| Per-request timeout (default |
| Override the API base URL |
| Fail instead of auto-refreshing an expired access token |
| Machine-readable output |
Command-specific: gen --n <count>, edit --image <file> (repeatable, max 5),
models --models <a,b,c>.
Help
Every command carries its own help text, so an agent can learn the tool from the tool itself:
codex-img # overview: command table + notes
codex-img help gen # full reference for one command
codex-img gen --help # same thing
codex-img --versionEach command's help lists its required arguments, every option, runnable
examples, and the behaviour that is easy to get wrong — for example that the
endpoint ignores model, or that edit takes at most five reference images.
An unknown command exits with code 2 and lists the valid commands.
Multiple images
--n requests more than one image: the first is written to --out, the rest
to <out>-2.png, <out>-3.png, …
codex-img gen --prompt "four variations of a brass compass" --n 4 --out compass.pngMCP
The mcp command speaks JSON-RPC 2.0 over stdin/stdout. Any MCP client that
speaks stdio can use it.
{
"mcpServers": {
"codex-img": {
"command": "node",
"args": ["/absolute/path/to/codex-img-cli/bin/codex-img.mjs", "mcp"]
}
}
}With Claude Code:
claude mcp add codex-img -- node /absolute/path/to/codex-img-cli/bin/codex-img.mjs mcpTwo tools are exposed:
Tool | Parameters |
|
|
|
|
The tool descriptions spell out how to write the prompt, why out_path should
always be explicit, and that model and size are ignored by this endpoint —
so an agent calls it correctly without any extra documentation.
The same request, both ways:
|
|
|
|
What the endpoint really honours
OpenAI shipped GPT-Image-2.5 on 2026-09-08, split on the API side into
gpt-image-2.5-flare (fast) and gpt-image-2.5-sunburst (precise). On this
subscription channel you cannot pick between them.
codex-img models probes it first-hand — measured on a Pro subscription:
Requested model | Result | Returned size | Returned quality |
| HTTP 200 | 1448x1086 | low |
| HTTP 200 | 1448x1086 | low |
| HTTP 200 | 1448x1086 | low |
| HTTP 200 | 1448x1086 | low |
A model id that does not exist still returns 200, so the endpoint ignores
the model field outright. size is ignored too: asking for 1024x1024 comes
back as 1254x1254 or 1448x1086, not even satisfying the public Images API
rule that side lengths be multiples of 16.
That also explains why openai/codex still hardcodes
const IMAGE_MODEL: &str = "gpt-image-2" and yet delivers 2.5 quality: the
backend changed, the frontend identifier did not.
Conclusion: choosing between Flare and Sunburst requires an official API key
against api.openai.com. On the subscription channel, you get whatever the
backend serves.
Requirements and limits
Needs a ChatGPT subscription, and either
codex loginon this machine or acodex-img loginof your own.This calls an undocumented internal endpoint that is not part of the OpenAI developer documentation. It can change or disappear at any time.
Using subscription credentials from a non-official client violates the OpenAI terms of service. Self-use is your own call; do not redistribute it or resell access.
Image generation draws from a quota pool separate from chat (
limit_id == "image_gen"in the Codex source).Codex rotates refresh tokens. If Codex CLI refreshes at the same moment, you can hit "refresh token already used" — run
codex loginonce and retry.Output PNGs carry C2PA metadata and an invisible watermark, same as anything produced by ChatGPT or Codex.
Development
npm test # node:test, no network, no dependencies
npm link # run the CLI from your working treeLayout:
bin/codex-img.mjs executable entry point
src/cli.mjs argument parsing and command dispatch
src/help.mjs the command registry and all help text
src/client.mjs endpoint calls, base64 payloads, file writing
src/auth.mjs credential file, token refresh, atomic write
src/credentials.mjs the credential store this CLI manages
src/login.mjs OAuth sign-in (browser and device code flows)
src/mcp.mjs MCP stdio server and tool schemas
src/version.mjs version, read from package.json
scripts/cleanup-credentials.mjs removes the credentials on uninstallCI runs the suite on Linux, macOS and Windows against Node 20, 22 and 24.
License
MIT — see LICENSE.
Related work
Independent implementations of the same call, useful as cross-checks:
headroomlabs-ai/headroom— Pythoncaozhiyuan/copilot-api— TypeScriptkittors/CliRelay— Go, also records the "model field is ignored" findingNomaDamas/CozyClay— NodeNousResearch/hermes-agent— Hermes, with a built-inopenai-codeximage provider
If you would rather not maintain your own code, Hermes already wraps this
and can expose OAuth providers as an OpenAI-compatible endpoint via
hermes proxy.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models and 10 tools: up to 4 images per call, SVG vectorization, editing and more. Remote MCP with OAuth, no API keys. Pay per image, no subscription.
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models. Up to 4 images per call, SVG vectorization, background removal, upscaling and image-to-video. Remote MCP with OAuth, no API keys.
Generate AI images and videos from any compatible MCP client.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables MCP-capable agents to generate and edit images through Gemini or OpenAI, returning an absolute file path instead of image bytes to keep context windows clean.1MIT
- AlicenseAqualityBmaintenanceEnables any MCP client to generate and edit images through ChatGPT's Codex backend, saving them locally with no API key or per-image billing.5125 npm10Apache 2.0
- AlicenseNot gradedqualityBmaintenanceExposes Codex's built-in image generation to any MCP-capable agent, returning file paths, pixel dimensions, and the prompts used, with support for image-to-image editing via reference images. Ships scenario presets (Xiaohongshu, video cover, poster, book/album cover and more) plus built-in prompt assembly and catalog listing tools so agents can generate or preview prompts without spending credits.136MIT
- AlicenseNot gradedqualityCmaintenanceEnables coding agents and other MCP clients to generate images from text prompts and edit, restyle, or extend existing images through an OpenAI-compatible /v1/images API. Results are returned both inline as image content blocks and as files saved to disk, so agents can view and reuse them within a normal task.274 npm1MIT
