image-generation-mcp

Ask your agent for a picture, and it gets back a file path — not a wall of base64. The server generates the image with Gemini, OpenAI, or any image model on the Vercel AI Gateway (Flux, Grok Imagine, Recraft, Seedream, …), writes it to disk, and returns only the absolute path. Your context window stays clean, and the file is right there for the agent to open, move, or hand to another tool.

Features

• One tool, no ceremony. generate_image(prompt, images, aspect_ratio) — that's the whole API.

• Paths, not payloads. Returns an absolute file path, so a 1.5 MB PNG costs you ~60 tokens instead of ~2 million.

• Three providers, auto-selected. Set whichever API key you have. Several set? IMAGE_PROVIDER decides.

• Dozens of models through one key. The Vercel AI Gateway provider reaches Flux, Grok Imagine, Recraft, Seedream, and OpenAI image models — from $0.007 per image.

• Image-to-image. Pass up to 4 reference images to restyle, edit, or combine them.

• Flexible inputs. A reference can be a local path, an http(s) URL, a data: URI, or bare base64 — the server figures out which.

• Both transports. stdio for local clients, streamable HTTP (localhost-bound) when you need a port.

• Honest errors. No retries that mask a bad key, no silent provider fallback. When the API says 429, your agent sees 429 — every expected failure (input, config, provider, download) comes back as a tool error carrying the exception type and message.

• Small enough to read. ~650 lines of source, no file over 100 lines, strict-typed throughout.

Related MCP server: image2-mcp

Prerequisites

Billing note. Image models are not free tier on Gemini or OpenAI. A Gemini key without billing enabled returns 429 ... limit: 0 for every image model. Vercel AI Gateway bills per image from your gateway credits — see pricing.

Quick Start

git clone https://github.com/farukcan/image-generation-mcp.git
cd image-generation-mcp
uv sync

cp .env.example .env      # add GEMINI_API_KEY, OPENAI_API_KEY, or AI_GATEWAY_API_KEY
uv run pytest -m smoke    # generates a real image into out/

That last command is the fastest way to confirm your key works end to end — it prints the path of the image it just made.

Add it to your agent

Claude Code

claude mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uvx --from git+https://github.com/farukcan/image-generation-mcp image-generation-mcp

uvx fetches, builds, and caches the package on first run — there is nothing to install beforehand and nothing to keep updated by hand.

Prefer a checkout you can edit? Point it at the directory instead:

claude mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uv run --directory /absolute/path/to/image-generation-mcp image-generation-mcp

Add -s user to make it available in every project instead of just this one. Verify with claude mcp list, and remove it with claude mcp remove image-generation.

Gemini CLI

Same flags, same shape:

gemini mcp add image-generation \
  -e OPENAI_API_KEY=sk-... \
  -- uvx --from git+https://github.com/farukcan/image-generation-mcp image-generation-mcp

Cursor, Windsurf, Claude Desktop, and everything else

These read a JSON config file (.cursor/mcp.json, claude_desktop_config.json, …). The entry is the same everywhere:

{
  "mcpServers": {
    "image-generation": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/farukcan/image-generation-mcp",
        "image-generation-mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "OUT_DIR": "/absolute/path/where/images/should/land"
      }
    }
  }
}

Set OUT_DIR explicitly for GUI clients — they often launch with a working directory you did not expect, and out/ would land there.

As an HTTP service

uv run image-generation-mcp --transport http --port 8000

Serves the streamable-HTTP endpoint at http://127.0.0.1:8000/mcp. It binds to loopback only and has no authentication, so put it behind a proxy before exposing it.

The tool

generate_image(prompt: str, images: list[str] | None = None, aspect_ratio: str = "1:1") -> str

Returns the absolute path of the written file, e.g. /path/to/out/20260827-172746-c9b3.png. Names are YYYYmmdd-HHMMSS-xxxx, so results sort chronologically and never collide.

On aspect ratios: Gemini honours all ten. OpenAI accepts only three sizes, so ratios collapse to the nearest of 1024x1024, 1536x1024, or 1024x1536 — asking for 16:9 there gets you 3:2. Vercel AI Gateway gets the same three sizes (its Images endpoint does not forward an aspect ratio field, and OpenAI models behind it reject any other size). Flux honours them; some models, such as Grok Imagine, ignore size and pick their own shape.

Configuration

Every setting is an environment variable. A .env file in the working directory (or any parent) is loaded as a fallback; real environment variables always win.

Start the server with no API key at all and the first request fails loudly, naming the variables it looked for.

How it works

flowchart LR
    A([MCP client]) -->|generate_image| B[server.py]
    B --> C[aspect.py<br/>validate ratio]
    B --> D[sources.py + download.py<br/>path / URL / base64 → bytes]
    B --> E{"registry.py<br/>which provider?"}
    E -->|GEMINI_API_KEY| F[gemini_provider.py<br/>Interactions API]
    E -->|OPENAI_API_KEY| G[openai_provider.py<br/>generate / edit]
    E -->|AI_GATEWAY_API_KEY| V[vercel_provider.py<br/>gateway generate / edit]
    F --> H[output.py<br/>write into OUT_DIR]
    G --> H
    V --> H
    H -->|absolute path| A

Each module does one thing and stays under 100 lines. Providers are cached per resolved config, so an SDK client and its connection pool are reused across calls rather than rebuilt every request.

Providers

Deliberate quirks worth knowing:

• Gemini's image response_format only accepts image/jpeg as an explicit MIME type, so the server does not request one and names the file after whatever comes back.

• input_fidelity is never sent to OpenAI — gpt-image-2 rejects it with a 400 and applies high fidelity on its own.

• The Vercel provider covers image-only gateway models. Multimodal models that generate images through chat completions (Gemini "Nano Banana", GPT-5) are not wired up; use the Gemini or OpenAI provider for those.

• Not every gateway model edits. A model without image input fails reference-image calls with the gateway's own error — there is no silent fallback.

Vercel AI Gateway pricing

The default, bfl/flux-3-image-klein, is the cheapest model we found that both honours size and edits faithfully. Spot checks on 2026-11-03, one bicycle prompt each:

Source: GET https://ai-gateway.vercel.sh/v1/models, fetched 2026-11-03. Prices are USD and change — check the model list before relying on them.

Billed per image (the price is for the default size unless a tier is listed):

Billed per token (cost per image depends on size and quality):

No price listed: bfl/flux-2-flex, bfl/flux-2-klein-4b, bfl/flux-2-klein-9b, bfl/flux-2-max, bfl/flux-2-pro, prodia/flux-fast-schnell, topaz/wonder-3.5.

Development

uv run ruff check . && uv run ruff format --check .
uv run mypy
uv run pytest              # unit tests, all providers mocked
uv run pytest -m smoke -s  # real API calls; costs money, prints the paths

Smoke tests are deselected by default so a normal pytest run never spends money. test_edits_a_real_image costs two generations, since it makes its own reference image. test_vercel_generates_and_edits forces the Vercel provider and also costs two generations on VERCEL_IMAGE_MODEL (about $0.02 on the default).

The logo and the screenshot are generated too — edit the scripts, not the SVGs:

uv run python media/generate_logo.py
uv run python media/generate_screenshot.py

The 100-line-per-file ceiling is a design constraint, not an accident: it keeps every module reviewable in one screen. Split rather than stretch.

Troubleshooting

License

MIT © Ömer Faruk Can