mcpField
C
Codex Images

Codex Images

Local
github.comMedia & Design0Updated 3d ago
RepositoryVisit website

About Codex Images

Codex Images is an MCP server for generating and editing images through the Codex Images endpoint using a ChatGPT account. It supports local stdio and self-hosted HTTP deployment, and returns verification details with image artifacts.

Key features

  1. 01Generate and edit images
  2. 02Edit with reference images and masks
  3. 03Run parallel, variant and chained batches
  4. 04Generate PNGs with native transparency
  5. 05Post-process to specified output sizes
  6. 06Return SHA-256, byte count and dimensions

Use cases

  1. 01Generate new images for a project
  2. 02Modify an image using references and a mask
  3. 03Create batches of brand-consistent image variants
  4. 04Obtain a transparent PNG at an exact size

MCP support

The MCP server exposes image generation, editing and artifact retrieval tools to clients. Connect locally over stdio or through a self-hosted HTTP server with bearer authentication.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "jlmoreno00-codex-images": {
      "command": "uvx",
      "args": [
        "codex-images-mcp"
      ],
      "env": {
        "CODEX_IMAGES_HTTP_TOKEN": "<CODEX_IMAGES_HTTP_TOKEN>"
      }
    }
  }
}
Run commanduvx codex-images-mcp
Environment variables to set
CODEX_IMAGES_HTTP_TOKENSecretBearer token. The image listens on 0.0.0.0 and refuses to start without this.

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypicodex-images-mcp0.1.1
ocighcr.io/jlmoreno00/codex-images-mcp:0.1.1

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project README

codex-images-mcp

Generate and edit images from any MCP client with gpt-image-2 on the ChatGPT plan you already pay for. No OpenAI API key, no per-image bill.

codex-images-mcp is an MCP server for the Codex Images endpoint. It runs locally over stdio, or as a self-hosted HTTP server that your laptop, your VPS agents and your Pi / Gentle Shell sessions can share. Every image comes back as a verifiable artifact: SHA-256, byte count, MIME type and real dimensions.

Unofficial. Not affiliated with or endorsed by OpenAI. It signs in with your own ChatGPT account and uses the same endpoint as the Codex CLI. You are bound by OpenAI's terms for your account, and image generation counts against your plan's limits.

What you get

  • Two tools: codex_images (generate/edit) and codex_images_artifact (fetch an image by URI, inline or through a short-lived signed download).
  • Batches: parallel, variants, chain and branded-parallel (every image references a shared anchor for brand-consistent sets).
  • Edits with references and masks: up to five references per request, HTTPS URLs or inline images.
  • Native transparency: real alpha PNGs from the model, with a warning when a result comes back opaque.
  • Exact output sizes: native, exact, fit or cover post-processing, so a 1200×630 card is 1200×630.
  • Prompts sent verbatim: no hidden rewriting model in between.
  • Optional API-key engine: set CODEX_IMAGES_ENGINE=api with an OPENAI_API_KEY to choose the model yourself (Images 2.6 gpt-image-2.6-sunburst / -flare), with quality up to max and complexity control. This engine is billed to your API account. On the default ChatGPT plan route OpenAI chooses the model, and the API selectors (model, quality, complexity) are ignored.
  • Self-hosting that is safe by default: built-in bearer auth, refuses to listen publicly without a token, SSRF-hardened URL fetching (HTTPS, public addresses only, pinned IP, no redirects), no server paths in results.
  • Its own ChatGPT session: codex-images-mcp login uses a device code and keeps a separate session, so it never rotates (and breaks) your Codex app's sign-in.

Quick start (local, stdio)

uvx --from codex-images-mcp codex-images-mcp login     # sign in once (device code)
uvx --from codex-images-mcp codex-images-mcp setup     # register in Claude Code, Claude Desktop, Codex, Cursor, OpenCode

Or try it from the terminal:

uvx --from codex-images-mcp codex-images-mcp generate "a ceramic mug, studio light" --transparent --pretty

Already signed in to the Codex CLI? codex-images-mcp can use that login read-only until its token expires. It never refreshes it; run login for a session of its own.

Example output

Example outputs from gpt-image-2 via this server. The pictures are resized for this page. A transparent generate, and an edit that sends a reference plus a mask, are written up in docs/examples.md.

Generate: a speckled ceramic mug on a transparent background. Edit + mask: the mug with a small stamped coffee bean on the front.

The generate on the left used the prompt a ceramic mug, studio light with transparent set. The model returned a 1536×1024 PNG, 1,745,462 bytes, sha256 e0d0338218529ca36e0d64e92eb2737c6794b392343f1a5ab32884a49dab48ba. The edit sent that mug as the reference, with a mask over the front, and asked for a small dark brown stamped coffee bean. It returned a 1536×1024 PNG, sha256 7c5b28d4950f5207c111f875ef9d19349e06be3da43ce1200d2d8d2c678b9ba5. The camera angle shifted slightly. A mask is a hint, and the model may adjust the whole frame.

The generate result is a PNG with a real alpha channel. The checkerboard is only a backdrop, so the transparent background is visible:

The generated mug composited on a checkerboard so the transparent background is visible.

Also in this folder: an off-white generate, the edit on a checkerboard, and 1200px transparent PNGs of the generate and the edit.

Self-hosted (HTTP)

export CODEX_IMAGES_HTTP_TOKEN=$(openssl rand -hex 32)
docker compose up -d
docker compose run --rm codex-images codex-images-mcp login

Then point your clients at https://your-host/mcp/ with Authorization: Bearer $CODEX_IMAGES_HTTP_TOKEN. See docs/self-hosting.md for the reverse proxy, signed downloads and every setting.

Pi and Gentle Shell

pi-codex-images is a Pi extension for a self-hosted server. It reads the local files you authorize, sends them inline, and writes verified results atomically into your project:

pi install npm:pi-codex-images

Documentation

  • MCP tools reference: inputs, results, error codes.
  • CLI: generate, login, logout, setup, status, uninstall.
  • Self-hosting: Docker, reverse proxy, configuration, security model.
  • Examples: batches, edits, masks, transparency, exact sizes.
  • Comparison: how this differs from similar projects.

Credits

codex-images-mcp started as a fork of VelmoAI/codex-imagen by wauwa. The installer and much of the original structure come from there. The OAuth token handling derives from codex-image-gen by Small Turtle 2. The generation engine was replaced with the native Codex Images endpoint, and the prompt-rewriting and chroma-key layers were removed.

License

MIT. See LICENSE and NOTICE.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.