gpt-image-mcp

A tiny, self-contained MCP server that gives Claude Code and Claude Desktop image generation and editing via OpenAI's gpt-image-2 (and other GPT Image models). Every result is saved to disk and returned inline, so Claude can both wire the file into your project and show you the image.

Two tools:

• generate_image — text → image (UI mockups, icons, hero art, diagrams, social graphics). GPT Image renders in-image text well, so describe any text literally.
• edit_image — image(s) + instruction → image (restyle, composite, inpaint with a mask, outpaint).

This runs locally over stdio. It is for Claude Code and Claude Desktop, which support local servers. It is not a remote connector and will not appear in claude.ai in the browser (that requires a hosted, OAuth-protected server).

---

Prerequisites

• Python 3.10+
• uv (recommended) or pip
• An OpenAI API key with credits. ⚠️ gpt-image-2 may require Organization Verification on your OpenAI org — without it, calls return HTTP 403. Verify under OpenAI dashboard → Settings → Organization.

---

Install (do this on each PC after cloning)

git clone <your-repo-url> gpt-image-mcp
cd gpt-image-mcp
./install.sh

On Windows (PowerShell), use the equivalent script:

git clone <your-repo-url> gpt-image-mcp
cd gpt-image-mcp
.\install.ps1
# if blocked by execution policy:
#   powershell -ExecutionPolicy Bypass -File .\install.ps1

The installer (install.sh / install.ps1) installs the dependencies and then prints the exact config for both clients with the absolute paths already filled in for that machine (paths JSON-escaped where needed). Copy what it prints.

Tip: paths differ per machine, so re-run ./install.sh on each PC rather than copying a config file between them.

---

Configure Claude Code

Export your key, then run the command install.sh printed (it looks like this):

export OPENAI_API_KEY=sk-...
claude mcp add gpt-image --scope user \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  -- uv run --project /abs/path/to/gpt-image-mcp gpt-image-mcp

--scope user makes it available in every project on that machine. Verify with claude mcp list, or /mcp inside a session.

--project (not --directory) is deliberate: it stops uv from changing the working directory into the repo, so the server inherits the directory you launched Claude Code from. With no IMAGE_OUTPUT_DIR set, images then save to ./generated-images inside whatever project you're working in. Want a fixed location instead? Add -e IMAGE_OUTPUT_DIR="/abs/path" to the command. You can also override per call with the tool's output_dir argument.

---

Configure Claude Desktop

Add the block install.sh printed under "mcpServers" in claude_desktop_config.json, replace the key, and fully quit and relaunch Desktop.

{
  "mcpServers": {
    "gpt-image": {
      "command": "/absolute/path/to/uv",
      "args": ["run", "--project", "/abs/path/to/gpt-image-mcp", "gpt-image-mcp"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "IMAGE_OUTPUT_DIR": "/Users/joe/gpt-image-output"
      }
    }
  }
}

Config file location:

OS	Path
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%\Claude\claude_desktop_config.json

Open it from Desktop via Settings → Developer → Edit Config.

Two gotchas that bite on Desktop specifically:

1. Use the absolute path to uv (or to .venv/bin/gpt-image-mcp). Desktop launches configs with a minimal PATH, so bare uv/npx often fail even though they work in your terminal. Find it with which uv.
2. Set IMAGE_OUTPUT_DIR to an absolute path. Desktop's working directory is unpredictable, so without this you may not find your images.

---

Manual setup (no uv, or Windows)

python3 -m venv .venv
# macOS/Linux:
.venv/bin/pip install -e .
# Windows (PowerShell):
.\.venv\Scripts\pip install -e .

Then point the command at the installed script:

• macOS/Linux: /abs/path/to/gpt-image-mcp/.venv/bin/gpt-image-mcp
• Windows: C:\abs\path\to\gpt-image-mcp\.venv\Scripts\gpt-image-mcp.exe

(args can be [] since the script is the entry point), and set OPENAI_API_KEY / IMAGE_OUTPUT_DIR in env.

---

Usage

Just ask in natural language:

• "Generate a 1536x1024 hero image: a calm modern fintech dashboard, soft gradients, the headline 'Self-Directed IRAs, Simplified' in clean sans-serif."
• "Make three square app icons for a swim-tracking tool — minimalist line art."
• "Edit ./logo.png to put it on a transparent... " → use model="gpt-image-1.5" for transparency (see limitations).
• In Claude Code: "Generate a background image and use it in hero.tsx." — it saves the file into the project and references it for you.

Tool parameters (most useful)

generate_image: prompt, model (default gpt-image-2), size (1024x1024 | 1536x1024 | 1024x1536 | auto), quality (low|medium|high|auto), n (1–10), background (auto|opaque|transparent), output_format (png|jpeg|webp), output_dir, filename.

edit_image: prompt, images (list of paths), mask (PNG path), plus the same model/size/quality/n/output_format/output_dir/filename.

---

Limitations & notes

• No transparent background on gpt-image-2. Passing background="transparent" to it will error. For alpha (icons/UI assets), pass model="gpt-image-1.5" or another alpha-capable model.
• Cost. GPT Image is token-priced; most generations land roughly $0.04–$0.35 each depending on size/quality. The tool prints a rough estimate (rates are hardcoded in server.py and may drift — trust your OpenAI dashboard).
• Cheap iteration. Use model="gpt-image-1-mini" to rough things out, then re-render the final with gpt-image-2.
• Org verification. A 403 almost always means your OpenAI org isn't verified for GPT Image yet.

License

MIT — see LICENSE.