Image Generation MCP Server
MCP server for AI image generation via OpenAI, Stable Diffusion (SD WebUI), or placeholders.
Ask AI about Image Generation MCP Server
Powered by Claude · Grounded in docs
I know everything about Image Generation MCP Server. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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) andlist_providers - MCP resources --
info://providers,image://{id}/viewwith CDN-style transforms (format, resize, crop),image://{id}/metadata,image://list - MCP prompts --
select_provider(provider selection guidance) andsd_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
gosuprivilege 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:
| Extra | Includes |
|---|---|
mcp | fastmcp[tasks]>=3.0,<4 |
openai | openai>=1.0 |
all | fastmcp[tasks]>=3.0,<4 + openai>=1.0 |
dev | All above + pytest, ruff, mypy, pip-audit |
docs | mkdocs-material, mkdocstrings, mkdocs-llmstxt |
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
| Variable | Type | Default | Description |
|---|---|---|---|
IMAGE_GENERATION_MCP_SCRATCH_DIR | Path | ~/.image-generation-mcp/images/ | Directory for saved generated images |
IMAGE_GENERATION_MCP_READ_ONLY | bool | true | Hide write-tagged tools (generate_image) |
IMAGE_GENERATION_MCP_DEFAULT_PROVIDER | str | auto | Default provider: auto, openai, sd_webui, placeholder |
Providers
| Variable | Type | Default | Description |
|---|---|---|---|
IMAGE_GENERATION_MCP_OPENAI_API_KEY | str | -- | OpenAI API key; enables OpenAI provider when set |
IMAGE_GENERATION_MCP_SD_WEBUI_HOST | str | -- | SD WebUI URL (e.g. http://localhost:7860); enables SD WebUI provider when set. Deprecated alias: A1111_HOST. |
IMAGE_GENERATION_MCP_SD_WEBUI_MODEL | str | -- | SD WebUI checkpoint name for preset detection and override. Deprecated alias: A1111_MODEL. |
Authentication
| Variable | Type | Default | Description |
|---|---|---|---|
IMAGE_GENERATION_MCP_BEARER_TOKEN | str | -- | Static bearer token; enables bearer auth when set |
IMAGE_GENERATION_MCP_BASE_URL | str | -- | Public base URL for OIDC and artifact download links (e.g. https://mcp.example.com) |
IMAGE_GENERATION_MCP_OIDC_CONFIG_URL | str | -- | OIDC discovery endpoint URL |
IMAGE_GENERATION_MCP_OIDC_CLIENT_ID | str | -- | OIDC client ID |
IMAGE_GENERATION_MCP_OIDC_CLIENT_SECRET | str | -- | OIDC client secret |
IMAGE_GENERATION_MCP_OIDC_JWT_SIGNING_KEY | str | ephemeral | JWT signing key; required on Linux/Docker |
IMAGE_GENERATION_MCP_OIDC_AUDIENCE | str | -- | Expected JWT audience claim |
IMAGE_GENERATION_MCP_OIDC_REQUIRED_SCOPES | str | openid | Comma-separated required scopes |
IMAGE_GENERATION_MCP_OIDC_VERIFY_ACCESS_TOKEN | bool | false | Verify access token as JWT instead of id token |
Cost Control
| Variable | Type | Default | Description |
|---|---|---|---|
IMAGE_GENERATION_MCP_PAID_PROVIDERS | str | openai | Comma-separated paid provider names. Triggers elicitation confirmation on capable clients. Set to empty to disable. |
Performance
| Variable | Type | Default | Description |
|---|---|---|---|
IMAGE_GENERATION_MCP_TRANSFORM_CACHE_SIZE | int | 64 | Max cached transforms. Set to 0 to disable caching. |
Server
| Variable | Type | Default | Description |
|---|---|---|---|
IMAGE_GENERATION_MCP_EVENT_STORE_URL | str | file:///data/state/events | EventStore backend: file:///path (persistent, survives restarts) or memory:// (dev only) |
IMAGE_GENERATION_MCP_SERVER_NAME | str | image-generation-mcp | Server name shown to MCP clients |
IMAGE_GENERATION_MCP_INSTRUCTIONS | str | (dynamic) | System instructions for LLM context |
FASTMCP_LOG_LEVEL | str | INFO | Log level: DEBUG, INFO, WARNING, ERROR (controls FastMCP internals; use -v to set app loggers to DEBUG) |
IMAGE_GENERATION_MCP_HTTP_PATH | str | /mcp | HTTP endpoint mount path |
IMAGE_GENERATION_MCP_APP_DOMAIN | str | (auto) | MCP Apps widget sandbox domain. Auto-computed from BASE_URL for Claude; override for other hosts (see docs) |
CLI reference
image-generation-mcp serve [OPTIONS]
| Flag | Default | Description |
|---|---|---|
--transport | stdio | MCP transport: stdio, sse, or http (streamable-http) |
--host | 0.0.0.0 | Host to bind to (HTTP transport only) |
--port | 8000 | Port to listen on (HTTP transport only) |
--path | /mcp | HTTP endpoint mount path (HTTP transport only) |
-v, --verbose | -- | Enable debug logging |
MCP tools
| Tool | Tags | Task | Parameters | Description |
|---|---|---|---|---|
generate_image | write | task=True | prompt (str), provider (str, default "auto"), negative_prompt (str, optional), aspect_ratio (str, default "1:1"), quality (str, default "standard") | Generate an image, returns metadata + resource URIs |
show_image | -- | -- | uri (str) | Display an image as inline thumbnail preview with metadata |
list_providers | -- | -- | (none) | List available providers with availability info |
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
| URI | MIME Type | Description |
|---|---|---|
info://providers | application/json | Provider capabilities and supported features |
image://{id}/view{?format,width,height,quality} | varies | Image with optional transforms (format conversion, resize, crop) |
image://{id}/metadata | application/json | Sidecar JSON with generation provenance |
image://list | application/json | All registered images |
The image://{id}/view resource template supports CDN-style transforms:
- No parameters -- original bytes unchanged
format-- convert topng,webp, orjpegwidth+height-- center-crop to exact dimensionswidthonly orheightonly -- proportional resizequality-- compression quality for lossy formats (default 90)
MCP prompts
| Prompt | Parameters | Description |
|---|---|---|
select_provider | (none) | Provider selection guidance -- strengths, use cases, and selection rules for each provider |
sd_prompt_guide | (none) | Stable Diffusion prompt writing guide -- CLIP tag format, quality tags, negative prompts, BREAK syntax, aspect ratios |
Providers
| Provider | Best for | Requires |
|---|---|---|
| OpenAI | Text, logos, typography, general-purpose | IMAGE_GENERATION_MCP_OPENAI_API_KEY |
| SD WebUI | Photorealism, portraits, anime, artistic styles | Running SD WebUI + IMAGE_GENERATION_MCP_SD_WEBUI_HOST |
| Placeholder | Testing, drafts, CI | Nothing (always available) |
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-1only) - Quality levels:
standard(mapped tohighfor gpt-image-1),hd(mapped tohigh) - 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_promptfield - Checkpoint override: Specify
modelto overridesd_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:
- Multi-auth -- both bearer token and OIDC configured; either credential accepted
- Bearer token -- set
IMAGE_GENERATION_MCP_BEARER_TOKEN - OIDC -- full OAuth 2.1 flow via OIDC environment variables
- 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
