Metadata-Version: 2.5
Name: codex-images-mcp
Version: 0.1.1
Summary: Self-hosted MCP server for Codex Images (gpt-image-2 on your ChatGPT plan): stdio and HTTP, verifiable artifacts, masks
Project-URL: Homepage, https://github.com/JlMoreno00/codex-images-mcp
Project-URL: Repository, https://github.com/JlMoreno00/codex-images-mcp
Project-URL: Issues, https://github.com/JlMoreno00/codex-images-mcp/issues
Author: wauwa, JlMoreno00
License: MIT
License-File: LICENSE
License-File: NOTICE
Keywords: ai,cli,codex,gpt-image,image generation,mcp,openai,sdk
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: click>=8.1
Requires-Dist: mcp<2,>=1.27
Requires-Dist: pillow>=10.0
Requires-Dist: tomli-w>=1.0
Provides-Extra: dev
Requires-Dist: httpx; extra == 'dev'
Requires-Dist: pytest-mock; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: pyyaml; extra == 'dev'
Requires-Dist: starlette>=0.40; extra == 'dev'
Requires-Dist: uvicorn>=0.30; extra == 'dev'
Provides-Extra: http
Requires-Dist: starlette>=0.40; extra == 'http'
Requires-Dist: uvicorn>=0.30; extra == 'http'
Description-Content-Type: text/markdown

# 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.

<!-- mcp-name: io.github.JlMoreno00/codex-images-mcp -->

> **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)

```bash
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:

```bash
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](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.](docs/example-before-after.jpg)

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.](docs/example-generate-checker.jpg)

Also in this folder: an [off-white generate](docs/example-generate-hero.jpg), the [edit on a checkerboard](docs/example-edit-checker.jpg), and 1200px transparent PNGs of the [generate](docs/example-generate.png) and the [edit](docs/example-edit-1200.png).

## Self-hosted (HTTP)

```bash
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](docs/self-hosting.md) for the reverse proxy, signed downloads and every setting.

## Pi and Gentle Shell

[`pi-codex-images`](packages/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:

```bash
pi install npm:pi-codex-images
```

## Documentation

- [MCP tools reference](docs/mcp.md): inputs, results, error codes.
- [CLI](docs/cli.md): `generate`, `login`, `logout`, `setup`, `status`, `uninstall`.
- [Self-hosting](docs/self-hosting.md): Docker, reverse proxy, configuration, security model.
- [Examples](docs/examples.md): batches, edits, masks, transparency, exact sizes.
- [Comparison](docs/comparison.md): how this differs from similar projects.

## Credits

codex-images-mcp started as a fork of [VelmoAI/codex-imagen](https://github.com/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](https://github.com/smturtle2/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](LICENSE) and [NOTICE](NOTICE).
