Skip to main content
Glama

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.


Related MCP server: claude-imagine

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.

Available Tools

2 tools
edit_imageA

Edit, restyle, or combine existing image(s) using a text instruction.

Use this for image-to-image work: modify an image, restyle it, composite several inputs into one, inpaint a masked region, or extend / outpaint.

Args: prompt: Instruction describing the desired edit or final result. images: One or more paths to input image files (PNG/JPEG/WEBP, <=50MB each). Multiple images are used together as references / inputs. mask: Optional path to a PNG mask. Transparent areas of the mask mark the region to edit/replace; opaque areas are preserved. model: GPT Image model. Default "gpt-image-2". size: "1024x1024", "1536x1024", "1024x1536", or "auto". quality: "low", "medium", "high", or "auto". n: Number of variations to generate (1-10). output_format: "png", "jpeg", or "webp". output_dir: Where to save. Defaults to $IMAGE_OUTPUT_DIR or ./generated-images. filename: Base filename without extension.

Returns: A text summary with the saved file path(s), followed by the image(s) inline.

Inputs: images (required), prompt (required), n, mask, +6 more.

generate_imageA

Generate image(s) from a text prompt with OpenAI GPT Image and save them to disk.

Use this to create new images from scratch: UI mockups, icons, hero images, diagrams, illustrations, and social/marketing graphics. GPT Image renders in-image text unusually well, so write any text you want to appear in the image literally and describe its placement.

Args: prompt: What to generate. Be specific about subject, style, composition, lighting, and any text that should appear in the image. model: GPT Image model. Default "gpt-image-2" (best quality + reasoning). Use "gpt-image-1-mini" for cheap/fast iteration, then re-render the final asset with "gpt-image-2". size: "1024x1024" (square), "1536x1024" (landscape), "1024x1536" (portrait), or "auto". gpt-image-2 also supports larger / 2K sizes. quality: "low", "medium", "high", or "auto". Higher is better and costs more. n: Number of images to generate (1-10). background: "auto", "opaque", or "transparent". NOTE: gpt-image-2 does NOT support "transparent" — pass model="gpt-image-1.5" (or another alpha-capable model) when you need a transparent background. output_format: "png", "jpeg", or "webp". output_dir: Directory to save images into. Defaults to $IMAGE_OUTPUT_DIR, or ./generated-images relative to the current working directory. filename: Base filename without extension. Defaults to a slug of the prompt plus a timestamp.

Returns: A text summary with the saved file path(s), followed by the image(s) inline.

Inputs: prompt (required), n, size, model, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: one creates new images from scratch, the other edits/restyles existing images. No overlap or ambiguity between them.

    Naming Consistency5/5

    Both tools use a consistent verb_noun pattern: generate_image and edit_image. The naming is predictable and follows the same convention.

    Tool Count3/5

    With only 2 tools, the set feels thin but is appropriate for a focused image generation server. It covers the two core operations without bloat, but is on the low end of the acceptable range.

    Completeness4/5

    The domain is image generation/editing, and both primary operations are covered. Minor gaps exist (e.g., no direct list/delete of generated images), but agents can work around those via the filesystem.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers