gpt-image-mcp
Enables image generation and editing via OpenAI's GPT Image models (gpt-image-2, gpt-image-1.5, etc.). Supports generating images from text prompts and editing existing images with instructions, masks, and compositing.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gpt-image-mcp Generate a 1024x1024 app icon for a fitness tracker with a running figure."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
pipAn 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.shOn 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.ps1The 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.shon 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 |
|
Windows |
|
Open it from Desktop via Settings → Developer → Edit Config.
Two gotchas that bite on Desktop specifically:
Use the absolute path to
uv(or to.venv/bin/gpt-image-mcp). Desktop launches configs with a minimalPATH, so bareuv/npxoften fail even though they work in your terminal. Find it withwhich uv.Set
IMAGE_OUTPUT_DIRto 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-mcpWindows:
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.pngto put it on a transparent... " → usemodel="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), passmodel="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.pyand may drift — trust your OpenAI dashboard).Cheap iteration. Use
model="gpt-image-1-mini"to rough things out, then re-render the final withgpt-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 toolsedit_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
Scored across 2 tools
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.
Both tools use a consistent verb_noun pattern: generate_image and edit_image. The naming is predictable and follows the same convention.
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.
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
Related MCP Connectors
MCP server for Qwen Image 3 AI image generation
MCP server for Grok Imagine AI video generation
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for OpenAI Sora AI video generation
Related MCP Servers
- AlicenseDqualityDmaintenanceAn MCP server that allows Claude to use OpenAI's image generation capabilities (gpt-image-1) to create image assets for users, which is particularly useful for game and web development projects.111 npm3MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables Claude Code to generate context-aware images using local GPU-powered diffusion models, either automatically during coding or on-demand via slash commands.23 npm1MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that enables Claude Code to generate images using Google's Gemini image generation models.MIT
- AlicenseNot gradedqualityDmaintenanceA local MCP server that enables Claude to generate images using the OpenAI API.21 npmMIT