Skip to main content
Glama
skyjoe66

gpt-image-mcp

by skyjoe66
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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: MCP Asset Generator

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
nNo
maskNo
sizeNoauto
modelNogpt-image-2
imagesYes
promptYes
qualityNohigh
filenameNo
output_dirNo
output_formatNopng

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains essential behaviors such as mask semantics (transparent areas edited, opaque preserved), file size and format constraints, output directory defaulting, and the return format (text summary plus inline images). It lacks explicit statements about side effects (e.g., whether input images are modified), but the described behavior is otherwise comprehensive and non-contradictory.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (purpose, usage, args, returns). Despite its length, each sentence contributes necessary information, and the organization makes it easy to scan. There is no tautology or redundant repetition of the tool name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This tool has 10 parameters, no output schema, and no annotations, so the description is the only source of contextual information. It fully covers all parameters, defaults, output directory behavior, and return value, making the tool self-contained for an agent. The explicit mask and output details fill the gap left by the absent schema descriptions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate, and it does. The Args section explains every parameter in plain language, including constraints (n 1-10, size options, image formats, per-file size limit) and crucial semantics like the mask's transparent/opaque behavior. This adds significant meaning beyond the raw property names and types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Edit, restyle, or combine existing image(s) using a text instruction,' which clearly identifies the action and resource. It immediately distinguishes this tool from generate_image by framing it as image-to-image work and listing specific operations (modify, restyle, composite, inpaint, outpaint).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly provides usage context: 'Use this for image-to-image work' and enumerates concrete scenarios, giving an agent clear signals for when to select this tool. However, it does not explicitly name the alternative tool (generate_image) or state when not to use this tool, so it only partially meets the 'explicit alternatives' criterion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
nNo
sizeNo1024x1024
modelNogpt-image-2
promptYes
qualityNohigh
filenameNo
backgroundNoauto
output_dirNo
output_formatNopng

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully explains behavior: saves to disk, returns a text summary plus inline images, and warns that gpt-image-2 does not support transparent backgrounds while recommending an alternative model. It also clarifies default directories and filename behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-organized with Args and Returns sections, front-loads the core purpose, and every sentence adds useful information. Despite its length, it is dense with practical guidance and avoids filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex tool with 9 parameters, no annotations, and no output schema, the description is remarkably complete. It covers all parameters, defaults, model-specific caveats, output behavior, and even prompt-writing tips, making it self-sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description must explain all 9 parameters. It does so thoroughly: each arg has meaning, defaults, and often extra guidance (e.g., size options, quality tradeoffs, background caveat, filename default). This goes far beyond the bare types in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description opens with 'Generate image(s) from a text prompt with OpenAI GPT Image and save them to disk,' which is a specific verb+resource+action. It clearly distinguishes itself from the sibling edit_image by emphasizing creation 'from scratch' and listing concrete use cases like UI mockups and icons.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states 'Use this to create new images from scratch' and enumerates example use cases, giving clear context. It does not name edit_image as an alternative for modifications, but the 'from scratch' phrasing strongly implies the boundary.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observededit_image
    • First observedgenerate_image
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.6/5.0
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

ActivityStale
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/skyjoe66/gpt-image-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server