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.

🎯 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

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

From source

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

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

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

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 © 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) — 简体中文