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:

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:

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

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