# gpt-image-mcp

> **Give Claude Code the image-generation superpower.** Say "draw me a picture", and
> Claude Code generates it right in your conversation using OpenAI **`gpt-image-2`** —
> no need to switch apps or copy prompts.

[![README 中文](https://img.shields.io/badge/%E4%B8%AD%E6%96%87-README-yellow)](README.zh-CN.md)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](#requirements)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/model_ctx_protocol-1.8-6a4caf)](https://modelcontextprotocol.io)

## 🎯 What is this?

**For Claude Code users:** this project plugs `gpt-image-2` image generation straight
into Claude Code as an MCP server. Install once, register once, and Claude Code gains a
native `generate_image` ability — you describe the image in plain language (any
language), and Claude Code produces the prompt, calls `gpt-image-2`, and hands you a
local PNG. If you've ever wanted Claude to "just draw it" instead of explaining it, this
is the missing piece.

It also works as a standalone CLI and with any other MCP host — the same core, everywhere.

**No ChatGPT Plus subscription needed** — just any `gpt-image-2`-capable API key.

Workflow:

```
You: "A cyberpunk orange tabby cat in a spacesuit, starfield, cinematic lighting"
  ↓  Claude Code optimizes your prompt into professional English (automatic)
  ↓  gpt-image-mcp calls OpenAI gpt-image-2
  ↓  PNG saved locally → absolute path returned
You: got your image ✓
```

---

## ✨ Features

- **Native Claude Code integration.** Register once, and Claude Code gains a real
  `generate_image` tool — describe any scene in plain language, get a local PNG back
  inside your chat.
- **Two entrypoints, one core.** The same generation logic powers both an MCP server
  and a plain CLI.
  - `gpt-image-mcp --mcp` → stdio MCP server with `generate_image` / `list_images` tools
  - `gpt-image-mcp "a cat in a spacesuit"` → one-shot CLI generation
- **Any OpenAI-compatible backend.** Point `OPENAI_BASE_URL` anywhere you like
  (resellers, proxies, self-hosted gateways).
- **Quality tiers** map to `gpt-image-2`'s own `low` / `medium` / `high` knob. No extra
  models, no extra cost surprises.
- **Keys never in code.** Everything is env-driven — secrets stay out of your repo.
- **Async-safe.** Images stream to disk as base64-decoded PNGs locally; the API never
  writes to your disk for you.

## 🧰 Requirements

- Python **3.10+**
- An OpenAI API key, or an OpenAI-compatible endpoint (reseller / gateway / self-hosted)
  that serves `gpt-image-2` (or a compatible model you set via `GPT_IMAGE_MODEL`).
- Python installable via `pip` or `uv`.

## 📦 Install

### From PyPI

```bash
pip install gpt-image-mcp           # pip
# or
uv tool install gpt-image-mcp       # uv
```

### From source

```bash
git clone https://github.com/Garfield-Wuu/gpt-image-mcp
cd gpt-image-mcp
python -m venv .venv
source .venv/bin/activate           # Windows: .venv\Scripts\activate
pip install -e .
```

## ⚙️ Configuration

All configuration is via environment variables:

| Variable             | Required | Default                     | Description                                              |
|----------------------|----------|-----------------------------|----------------------------------------------------------|
| `OPENAI_API_KEY`     | ✅       | —                           | Your API key (official or reseller). Never hardcode it.  |
| `OPENAI_BASE_URL`    | ❌       | `https://api.openai.com/v1` | Any OpenAI-compatible endpoint base URL (incl. `/v1`).   |
| `GPT_IMAGE_MODEL`    | ❌       | `gpt-image-2`               | Model name served by the endpoint.                       |
| `GPT_IMAGE_OUT`      | ❌       | `<cwd>/out`                 | Directory where generated PNGs are saved.                |

> **Tip:** The default base URL is the official OpenAI endpoint. To use a reseller or
> proxy, just set `OPENAI_BASE_URL` to its `/v1` root — nothing else changes.

## 🚀 Usage

### As an MCP server (Claude Code)

Register the server (replace `~/.venv` with your actual env path):

```bash
claude mcp add gpt-image -s user \
  --env OPENAI_API_KEY="$OPENAI_API_KEY" \
  --env OPENAI_BASE_URL="$OPENAI_BASE_URL" \
  --env GPT_IMAGE_OUT="$PWD/out" \
  -- gpt-image-mcp --mcp
```

Restart Claude Code, and two tools become available:

- **`generate_image`** — generate an image and save it locally.
  ```
  ┌─────────────────────────────────────────────────────────────┐
  │ "A cyberpunk orange tabby cat in a spacesuit …"             │
  │    → gpt-image-mcp → local PNG → absolute path returned    │
  └─────────────────────────────────────────────────────────────┘
  ```
  Parameters: `prompt` (required), `size`, `quality`, `out_name`.
- **`list_images`** — list previously generated PNGs (newest first).

**What to say in Claude Code:**

> "Draw a cyberpunk orange tabby in a spacesuit, starfield, cinematic, high quality."
> → triggers `generate_image`
>
> "Generate a 1536x1024 landscape hero shot: cyberpunk city in the rain, neon
> reflections." → set size + quality
>
> "Which images have I generated before?" → triggers `list_images`

No magic syntax needed — just describe the image in your own words, in any language.
Claude Code handles the rest.

### As a CLI

```bash
export OPENAI_API_KEY="sk-..."
gpt-image-mcp "a cyberpunk orange tabby cat, neon rain, cinematic" \
  --size 1536x1024 --quality high --out ./out/hero.png
```

Without `--no-interactive`, the CLI lets you pick size/quality interactively when a TTY
is present.

## 🖼️ Parameters

**`size`** — canvas orientation:

| Value        | Orientation |
|--------------|-------------|
| `1024x1024`  | Square      |
| `1536x1024`  | Landscape   |
| `1024x1536`  | Portrait    |

**`quality`** — `gpt-image-2`'s own quality knob (single model; trade-off is
speed/cost vs. detail):

| Value    | Use case                         |
|----------|----------------------------------|
| `low`    | Drafts / quick thumbnails        |
| `medium` | Balanced default                 |
| `high`   | Final hero art, more detail/slower |

## 🛠️ Development

```bash
pip install -e ".[dev]"
ruff check .            # lint
pytest                  # run tests
python -m build         # build sdist + wheel
```

Layout:

```
src/gpt_image_mcp/
├── img_core.py    # shared generation logic (no MCP dependency)
├── mcp_server.py  # FastMCP server: generate_image / list_images
└── __main__.py    # CLI + MCP entrypoints
```

## 🔐 Security

- **Your API key is never embedded in this package.** It is read from
  `OPENAI_API_KEY` at call time.
- Nothing is logged or transmitted beyond the single image-generation request.
- The `.env` and `out/` directories are git-ignored by default.

## 📝 Notes & caveats

- Each request typically takes ~10–60 s depending on endpoint and quality tier.
- This project is **not affiliated with OpenAI**; it's an independent MCP wrapper.
- `gpt-image-2` returns images as base64 by default, which this tool decodes and writes
  to disk locally. A `url` fallback is also handled.

## 📄 License

[MIT](LICENSE) © Garfield-Wuu.

## ⭐ Support

If this saved you a rabbit hole, a star is appreciated. Issues and PRs welcome.

---

## 🌐 Other languages / 其他语言

- [**中文版 README (README.zh-CN.md)**](/README.zh-CN.md) — 简体中文