# image-gen-mcp

An MCP server that lets Claude Code **generate real images to use in your projects** (banners, icons, backgrounds, textures, etc.) with OpenAI **gpt-image-2**, and **save them straight to a path you specify**. It is meant for producing production assets — not for mocking up UI designs.

> ภาษาไทย: ดู [README.th.md](./README.th.md)

## Tools

### `generate_image`
Generate a new image from a text prompt and write it to a file.

| param | values | default |
|---|---|---|
| `prompt` * | text description of the image | — |
| `output_path` * | where to save, e.g. `public/images/banner.png` | — |
| `quality` | `low` \| `medium` \| `high` \| `auto` | `medium` |
| `size` | `auto` \| `1024x1024` \| `1536x1024` (landscape) \| `1024x1536` (portrait) \| `2048x2048` \| `WxH` | `1024x1024` (`api_key` mode only) |
| `format` | `png` \| `jpeg` \| `webp` | inferred from `output_path` extension |
| `background` | `opaque` \| `transparent` \| `auto` (transparent needs png/webp) | `auto` |
| `compression` | 0-100 (jpeg/webp only) | — |
| `n` | 1-10 (if >1, saves `name-1.ext`, `name-2.ext`, ...) | `1` |
| `model` | override the model | `gpt-image-2` |

### `edit_image`
Edit / build on existing images. Pass 1-16 reference images, plus an optional mask for inpainting.

| param | values |
|---|---|
| `prompt` * | what to edit / create |
| `image_paths` * | 1-16 source (reference) image paths |
| `output_path` * | where to save the result |
| `mask_path` | (optional) mask for inpainting — transparent areas of the mask are what gets edited; must match the first image's dimensions |
| + `quality` / `size` / `format` / `background` / `compression` / `n` / `model` — same as `generate_image` |

Both tools return only `{ path, bytes, size, quality, ... }` — never the raw image bytes (to avoid flooding the agent's context). A relative `output_path` is resolved against the calling project's CWD, and parent directories are created automatically.

## Authentication

Two modes. `IMAGE_GEN_AUTH_MODE` picks between them (`auto` by default: an API key in the environment wins, otherwise a stored login is used).

### `api_key` — `OPENAI_API_KEY` (recommended)

Calls `api.openai.com/v1`. Every parameter above works. Billed to your API account.

### `chatgpt` — browser login

```bash
npx image-gen-mcp login     # opens a browser; also `status` and `logout`
```

Signs in with your ChatGPT account and generates on your **ChatGPT plan quota instead of API credit**. If you call a tool with no credential configured, the server asks the MCP client to open the same login URL (URL-mode elicitation) and retries the call once you're done — Claude Code supports this; `claude -p` does not, so use the CLI there.

Tokens are stored in `~/.image-gen-mcp/auth.json` (0600) and refreshed automatically. Codex's own `~/.codex/auth.json` is never read or written — sharing one rotating refresh token between two tools logs both out.

**This mode is a reduced feature set.** It goes through `chatgpt.com/backend-api/codex`, which accepts only `prompt`, `model`, `quality`, `background`, always returns PNG, and *silently ignores* everything else. Rather than hand back an asset that quietly isn't what was asked for, the tools reject the unsupported parameters:

| | `api_key` | `chatgpt` |
|---|---|---|
| `size` | yes | **rejected** — dimensions come from the prompt; say "landscape"/"portrait"/"square" in it |
| `n` > 1 | yes | **rejected** — one image per call |
| `format` | png / jpeg / webp | **png only** |
| `compression` | yes | **rejected** |
| `moderation` | yes | **rejected** |
| `mask_path` (inpaint) | yes | **rejected** |
| `background: transparent` | yes | yes |
| `quality` | yes | accepted, but not reliably honored — the response's actual `quality` is reported back, and a `notes` entry flags any difference |

**Caveats.** OpenAI publishes no OAuth flow for third-party apps: this reuses the login its own Codex CLI performs, including that client's ID and its two allow-listed loopback ports (1455/1457). It is undocumented, unsupported, and can break without notice. The resulting token is *not* accepted by the Platform API (`GET /v1/models` with one answers `403 Missing scopes: api.model.read`), which is why the two modes talk to different hosts. `api_key` remains the supported path.

## Install

```bash
cd image-gen-mcp
npm install
```

## Connect to Claude Code

For `api_key` mode, provide the key via the server's `env` block in your MCP config (no `.env` file required) — in a project `.mcp.json` or a user-scoped config. For `chatgpt` mode, drop the `env` block and run `npx image-gen-mcp login` instead:

```json
{
  "mcpServers": {
    "image-gen": {
      "command": "node",
      "args": ["/Users/palm/Desktop/projects/custom-mcp/image-gen-mcp/src/index.mjs"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}
```

Or add it via the CLI:

```bash
claude mcp add image-gen -e OPENAI_API_KEY=sk-... -- node /Users/palm/Desktop/projects/custom-mcp/image-gen-mcp/src/index.mjs
```

## Test

```bash
npm run selftest   # real in-memory MCP round-trip with a fake client — no key/network needed
OPENAI_API_KEY=sk-... npm run smoke   # one real API call (quality low) that verifies a valid PNG
```

## Pricing (approx., gpt-image-2, 1024x1024)

low ~$0.006 · medium ~$0.053 · high ~$0.211 per image — start at `medium`, use `high` only for final assets.