image-generation-mcp

Multi-provider image generation MCP server built on FastMCP. Generate images from Claude Desktop, Claude Code, or any MCP client using OpenAI, Stable Diffusion (SD WebUI), or a zero-cost placeholder provider.

Documentation | PyPI | Docker

Features

• Multi-provider architecture -- OpenAI (gpt-image-1, dall-e-3), SD WebUI (Stable Diffusion WebUI, compatible with AUTOMATIC1111/Forge/reForge), and a zero-cost placeholder provider
• Keyword-based auto-selection -- automatically picks the best provider for your prompt (text/logo -> OpenAI, photorealism/anime -> SD WebUI, test/draft -> placeholder)
• MCP tools -- generate_image (with background task support) and list_providers
• MCP resources -- info://providers, image://{id}/view with CDN-style transforms (format, resize, crop), image://{id}/metadata, image://list
• MCP prompts -- select_provider (provider selection guidance) and sd_prompt_guide (CLIP tag format, negative prompts, BREAK syntax)
• Image asset model -- content-addressed image registry with sidecar JSON metadata, thumbnail previews, and resource URI-based transforms
• Background tasks -- hybrid foreground (streaming progress) and background (polling) execution via task=True
• Read-only mode -- write tools hidden via mcp.disable(tags={"write"}) for safe read-only deployments
• Authentication -- bearer token, OIDC (OAuth 2.1), and multi-auth (both simultaneously)
• Docker -- multi-arch image with gosu privilege dropping, configurable PUID/PGID
• CI/CD -- test matrix (Python 3.11-3.14), ruff, mypy, pip-audit, gitleaks, CodeQL, semantic-release

Installation

From PyPI

# Core + MCP server
pip install image-generation-mcp[mcp]

# With OpenAI provider
pip install image-generation-mcp[all]

Available extras:

From source

git clone https://github.com/pvliesdonk/image-generation-mcp.git
cd image-generation-mcp
uv sync --extra all --extra dev

Docker

docker pull ghcr.io/pvliesdonk/image-generation-mcp:latest

Linux packages (.deb / .rpm)

Native packages with a hardened systemd service are available from GitHub Releases. See the systemd deployment guide for details.

Quick start

As MCP server (stdio)

# Placeholder only -- no API keys needed
IMAGE_GENERATION_MCP_READ_ONLY=false image-generation-mcp serve

# Generate your first image -- ask Claude or call via MCP client:
#   generate_image(prompt="a sunset over the ocean", provider="placeholder")

# With OpenAI
IMAGE_GENERATION_MCP_READ_ONLY=false \
IMAGE_GENERATION_MCP_OPENAI_API_KEY=sk-... \
image-generation-mcp serve

As MCP server (HTTP)

IMAGE_GENERATION_MCP_READ_ONLY=false \
image-generation-mcp serve --transport http --port 8000

With Docker Compose

docker compose up -d

See Docker deployment for volumes, UID/GID, and Traefik setup.

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "image-gen": {
      "command": "image-generation-mcp",
      "args": ["serve"],
      "env": {
        "IMAGE_GENERATION_MCP_READ_ONLY": "false",
        "IMAGE_GENERATION_MCP_OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "image-gen": {
      "command": "image-generation-mcp",
      "args": ["serve"],
      "env": {
        "IMAGE_GENERATION_MCP_READ_ONLY": "false"
      }
    }
  }
}

Configuration

All environment variables use the IMAGE_GENERATION_MCP_ prefix.

Core

Providers

Authentication

Cost Control

Performance

Server

CLI reference

image-generation-mcp serve [OPTIONS]

MCP tools

generate_image returns JSON metadata as TextContent with image_id, original_uri, resource_template, sizes, and provider, plus a ResourceLink to the image. Call show_image with the image URI to display it.

show_image returns a WebP thumbnail (max 512px, always under 1 MB) as ImageContent for inline display, plus JSON metadata. Full-resolution images are available via image:// resource URIs or create_download_link.

Supported aspect ratios: 1:1, 16:9, 9:16, 3:2, 2:3. Supported quality levels: standard, hd.

MCP resources

The image://{id}/view resource template supports CDN-style transforms:

• No parameters -- original bytes unchanged
• format -- convert to png, webp, or jpeg
• width + height -- center-crop to exact dimensions
• width only or height only -- proportional resize
• quality -- compression quality for lossy formats (default 90)

MCP prompts

Providers

OpenAI

Best for text rendering, logos, typography, and general-purpose generation.

• Models: gpt-image-1 (default), dall-e-3
• Formats: PNG (all models), JPEG and WebP (gpt-image-1 only)
• Quality levels: standard (mapped to high for gpt-image-1), hd (mapped to high)
• Negative prompt: Appended as "Avoid: {negative_prompt}" to the prompt
• Requires: IMAGE_GENERATION_MCP_OPENAI_API_KEY

SD WebUI (Stable Diffusion WebUI)

Best for photorealism, portraits, anime, and artistic styles. Compatible with AUTOMATIC1111, Forge, reForge, and Forge-neo.

• API: HTTP POST to /sdapi/v1/txt2img
• Model presets: Auto-detected from checkpoint name:
  • SD 1.5 (default): 768px base, 30 steps, CFG 7.0, DPM++ 2M sampler, Karras scheduler
  • SDXL: 1024px base, 35 steps, CFG 7.5, DPM++ 2M sampler, Karras scheduler
  • SDXL Lightning/Turbo: 1024px base, 6 steps, CFG 2.0, DPM++ SDE sampler, Karras scheduler
• Negative prompt: Native support via negative_prompt field
• Checkpoint override: Specify model to override sd_model_checkpoint
• Timeout: 180s (SDXL at high res on consumer GPUs)
• Requires: IMAGE_GENERATION_MCP_SD_WEBUI_HOST

Placeholder

Zero-cost solid-color PNG generation for testing and drafts.

• No dependencies: Pure Python PNG encoder (zlib + struct)
• Color: Deterministic from MD5 hash of prompt
• Always available -- no API key or service needed

Authentication

The server supports four auth modes:

1. Multi-auth -- both bearer token and OIDC configured; either credential accepted
2. Bearer token -- set IMAGE_GENERATION_MCP_BEARER_TOKEN
3. OIDC -- full OAuth 2.1 flow via OIDC environment variables
4. No auth -- default; server accepts all connections

Auth requires --transport http (or sse). It has no effect with --transport stdio.

See Authentication guide for setup details.

Development

git clone https://github.com/pvliesdonk/image-generation-mcp.git
cd image-generation-mcp
uv sync --extra all --extra dev
uv run pytest
uv run ruff check src/ tests/
uv run mypy src/

License

MIT