img-gen-mcp

img-gen-mcp is a local-first MCP server for image generation, editing, async jobs, batch runs, background removal, optimization, final asset delivery, and optional ACP-style automation.

It now includes workflow-aware image guidance, persisted workflow state, explicit step tracking, and an optional ACP HTTP surface so iterative image jobs can survive restarts and support full automation flows.

It combines:

• OpenRouter-first image generation

• Kilo Gateway support

• OpenAI and Gemini image generation

• provider auto-selection and model-driven routing

• async task submission and polling

• batch image generation for prompt sweeps and variants

• local image generation through OpenAI-compatible endpoints and local bridges for MLX, ComfyUI, Draw Things, and llama.cpp-compatible servers

• Streamable HTTP transport for remote deployments

• optional ACP-style HTTP automation routes layered on top of MCP

• local background cleanup with rmbg, imgly, and a shared Docker-backed withoutbg daemon

• web optimization with sharp

• deterministic prompt enhancement before generation

Features

• generate_image for OpenRouter-first generation with response normalization

• kilo_generate_image for Kilo Gateway routing

• provider auto-selection through provider=auto or model-driven inference

• list_image_models for provider/model discovery with warnings and capability hints

• get_provider_status for backend readiness and local bootstrap guidance

• get_model_capabilities for a compact capability summary

• edit_image for prompt-driven image editing

• local provider support for OpenAI-compatible endpoints and local bridges like MLX, ComfyUI, and Draw Things

• submit_task and get_task for async generation workflows

• batch_generate_image for running multiple prompts in one request

• create_workflow, update_workflow, get_workflow, and finalize_workflow for iterative interactive jobs

• add_workflow_step and close_workflow_step for explicit workflow lifecycle tracking

• resume_workflow for continuing a persisted workflow after restart

• analyze_image_result and suggest_next_step for image-backed follow-up guidance

• inspect_cutout and compare_variants for specialized analysis helpers

• background_remove for local cutouts and the shared local withoutBG daemon

• resize_image and auto_crop for deterministic local transforms

• optimize_image for web-ready re-encoding and compression

• finalize_image for a one-call local workflow that can remove background, trim, crop, and resize

• alpha stats and multi-background inspection sheets for post-processing QA

• prompt enhancement before generation

• automatic web optimization after background removal/finalize

• debug mode via IMAGE_MCP_DEBUG=1

Related MCP server: nano-banana-claude

Release Notes

• Workflow records are now persisted to .image-mcp-workflows.json and can be resumed after restart.

• add_workflow_step and close_workflow_step are available for explicit workflow lifecycle tracking.

• analyze_image_result and suggest_next_step now inspect the actual image file for structured guidance.

Asset Workflows

For SVG-style icons, logos, favicons, and game sprites, use the built-in asset workflow guidance in docs/public/asset-workflows.md.

That keeps the repository self-contained for npm/GitHub users without asking them to install extra marketplace skills.

Install

npm install -g img-gen-mcp

If you are running from a local checkout instead of npm, point your MCP client at node /absolute/path/to/img-gen-mcp/server.js rather than npx.

Configuration

Use the correct launch command for your setup:

• Local checkout: node /absolute/path/to/img-gen-mcp/server.js

• Published package: npx -y img-gen-mcp

• HTTP transport: npx -y img-gen-mcp http

Set these environment variables in your MCP client:

• IMAGE_MCP_DEFAULT_PROVIDER - default provider when none is supplied

• IMAGE_MCP_DEFAULT_MODEL - default model when none is supplied

• IMAGE_MCP_PROJECT_OUTPUT_DIR - optional project-specific output root

• IMAGE_MCP_DEFAULT_BG_BACKEND - default local cleanup backend (rmbg, imgly, or withoutbg)

• WITHOUTBG_DAEMON_URL - local daemon URL, defaults to http://127.0.0.1:8765

• WITHOUTBG_AUTOSTART=1 - auto-start the shared withoutBG Docker daemon on demand

• IMAGE_MCP_DEFAULT_BG_ALPHA_THRESHOLD - tighter default mask for logos/header assets

• IMAGE_MCP_PROMPT_ENHANCE=0 - disable deterministic prompt enhancement

• IMAGE_MCP_DEBUG=1 - include detailed tool errors and provider payloads

Local model environment variables:

• IMAGE_MCP_LOCAL_PROVIDER - selects openai-compatible, comfyui, drawthings, or mlx

• IMAGE_MCP_LOCAL_ENDPOINT - local HTTP base URL

• IMAGE_MCP_LOCAL_MODEL - local model slug

• IMAGE_MCP_LOCAL_AUTOSTART=1 - opt-in local service startup

• IMAGE_MCP_LOCAL_BOOTSTRAP=1 - opt-in bootstrap helper mode

• IMAGE_MCP_LOCAL_TIMEOUT_MS - request timeout for local endpoints

• IMAGE_MCP_LOCAL_API_KEY - optional local auth token

Transport and runtime flags:

• IMAGE_MCP_TRANSPORT=http - opt in to Streamable HTTP transport

• IMAGE_MCP_HTTP_HOST - host for HTTP transport, defaults to 127.0.0.1

• IMAGE_MCP_HTTP_PORT - port for HTTP transport, defaults to 3333

• IMAGE_MCP_ACP=1 - enable the optional ACP-style automation surface on HTTP transport

• IMAGE_MCP_ACP_PATH - ACP route prefix, defaults to /acp

Example MCP config for a local checkout:

{
  "mcp": {
    "img-gen-mcp": {
      "type": "local",
      "command": ["npx", "-y", "img-gen-mcp"],
      "enabled": true,
      "environment": {
        "IMAGE_MCP_DEFAULT_PROVIDER": "openrouter",
        "IMAGE_MCP_DEFAULT_MODEL": "openai/gpt-image-1",
        "IMAGE_MCP_DEFAULT_BG_BACKEND": "imgly",
        "WITHOUTBG_DAEMON_URL": "http://127.0.0.1:8765",
        "WITHOUTBG_AUTOSTART": "1"
      }
    }
  }
}

Example MCP config for the published package:

{
  "mcp": {
    "img-gen-mcp": {
      "type": "local",
      "command": ["npx", "-y", "img-gen-mcp"],
      "enabled": true,
      "environment": {
        "IMAGE_MCP_DEFAULT_PROVIDER": "openrouter",
        "IMAGE_MCP_DEFAULT_MODEL": "openai/gpt-image-1",
        "IMAGE_MCP_DEFAULT_BG_BACKEND": "imgly",
        "WITHOUTBG_DAEMON_URL": "http://127.0.0.1:8765",
        "WITHOUTBG_AUTOSTART": "1"
      }
    }
  }
}

Local examples:

{
  "mcp": {
    "img-gen-mcp": {
      "type": "local",
      "command": ["npx", "-y", "img-gen-mcp"],
      "enabled": true,
      "environment": {
        "IMAGE_MCP_LOCAL_PROVIDER": "mlx",
        "IMAGE_MCP_LOCAL_ENDPOINT": "http://127.0.0.1:8000/v1",
        "IMAGE_MCP_LOCAL_MODEL": "qwen3.5",
        "IMAGE_MCP_LOCAL_AUTOSTART": "1"
      }
    }
  }
}

See docs/public/clients.md for ready-to-use examples for Kilo, Cursor, and generic MCP clients.

ACP Automation

img-gen-mcp can expose an optional ACP-style HTTP surface for automation clients that want task and workflow primitives in addition to MCP tools.

Enable it with:

IMAGE_MCP_TRANSPORT=http IMAGE_MCP_ACP=1 npm start

Route overview:

• GET /acp/health

• GET /acp/agent

• GET /acp/tools

• POST /acp/tools/:tool_name

• POST /acp/tasks

• GET /acp/tasks/:task_id

• POST /acp/tasks/:task_id/cancel

• POST /acp/workflows

• GET /acp/workflows/:workflow_id

• POST /acp/workflows/:workflow_id/steps

• PATCH /acp/workflows/:workflow_id/steps/:step_id

• POST /acp/workflows/:workflow_id/finalize

The ACP layer reuses the same MCP tool implementations and workflow persistence. MCP remains the primary protocol, and ACP is an opt-in automation layer on top.

The package ships bundled skills under skills/ so other users can reuse the same workflow guidance when they install the package or browse the repository.

Use npm run test:acp to smoke-test the ACP routes locally.

Published Package

The package version is 0.11.0.

After this release is published to GitHub, you can publish to npm manually with:

npm publish

If you want to verify the release artifact first, run:

npm pack --dry-run

Guidance

• Use provider=auto when you want the server to infer the backend from a model slug.

• Use submit_task for long-running generations when your client prefers polling.

• Use batch_generate_image when you want multiple prompt variants without reconfiguring the client.

• Use get_provider_status before troubleshooting a local runtime so you can see the expected endpoint and startup hint.

• Use IMAGE_MCP_LOCAL_BOOTSTRAP=1 when you want the server to print setup guidance for the configured local adapter.

• Use the workflow tools when you want the server to return a workflow ID and suggested next steps instead of stopping after one tool call.

• Run the workflow persistence regression test with npm run test:workflow.

Workflow tools:

• create_workflow

• update_workflow

• get_workflow

• resume_workflow

• finalize_workflow

• analyze_image_result

• inspect_cutout

• compare_variants

• suggest_next_step

App Model Access

img-gen-mcp cannot automatically use the image models built into Cursor, Claude Code, or Codex.

It can only use a model source that is exposed to it as a separate provider or local HTTP endpoint.

If you want a zero-cloud setup, use a local backend such as MLX-VLM on macOS or an OpenAI-compatible local server like llama.cpp, LM Studio, ComfyUI, or a Draw Things bridge.

For local adapters, the package supports explicit input_mode, input_image, and reference_image flows so image-to-image and edit workflows can pass files or URLs directly.

Workflow

The typical pipeline is:

1. Generate an image

2. Remove background if needed

3. Inspect the cutout on multiple backgrounds

4. Optimize the final asset for the web

5. Save and ship the final PNG/WebP/JPEG/AVIF

For complex generation work, prefer a model-first flow: pick a model, let provider=auto resolve the backend, then use async polling or batch generation if your client needs better control.

Common Uses

• logos

• icons

• header artwork

• product photography

• realistic subject cutouts

• transparent PNG delivery

Models

Supported OpenRouter image models include:

• microsoft/mai-image-2.5

• openai/gpt-image-1

• openai/gpt-5-image-mini

• openai/gpt-5.4-image-2

• x-ai/grok-imagine-image-quality

• google/gemini-2.5-flash-image

• google/gemini-2.5-flash-image-preview

• google/gemini-3-pro-image-preview

• sourceful/riverflow-v2.5-fast

• sourceful/riverflow-v2.5-pro

• sourceful/riverflow-v2.5-fast:free

• sourceful/riverflow-v2-fast

• sourceful/riverflow-v2-pro

• recraft/recraft-v4.1-utility

• recraft/recraft-v4.1-vector

• recraft/recraft-v4.1-utility-pro

• recraft/recraft-v4.1-pro-vector

• recraft/recraft-v3

• black-forest-labs/flux.2-pro

• black-forest-labs/flux.2-flex

Recommended defaults:

• Photorealistic work: microsoft/mai-image-2.5 or openai/gpt-image-1

• Quick stylized work: x-ai/grok-imagine-image-quality

• Logos / vector-like work: recraft/recraft-v4.1-vector

• Broad prompt-following general use: sourceful/riverflow-v2.5-pro

Local backends

• openai-compatible for any /v1-style local server

• mlx for macOS local model wrappers

• comfyui for workflow-driven generation

• drawthings for a running macOS app bridge

• llama.cpp for a lightweight local OpenAI-compatible endpoint

Background Removal Backends

• rmbg - fastest lightweight local cleanup

• imgly - higher-quality local cleanup

• withoutbg - shared Docker-backed local daemon for harder edges, fur, and transparent cutouts

Start the shared daemon once:

docker compose -f withoutbg-daemon/docker-compose.yml up -d

If WITHOUTBG_AUTOSTART=1 is set, the MCP will try to start it automatically when backend=withoutbg is used.

If the MCP runs inside another container and the withoutbg daemon runs on the host, point the MCP at the host-published port:

WITHOUTBG_DAEMON_URL=http://host.docker.internal:8765

On Docker Desktop or OrbStack for macOS, host.docker.internal is the usual bridge from a container back to the host machine. If the MCP and withoutbg run in the same Docker network, you can also point WITHOUTBG_DAEMON_URL at the service name instead, such as http://withoutbg:8765.

Web Optimization

background_remove and finalize_image automatically run a web optimization pass after cleanup.

Use optimize_image directly when you want explicit control:

• PNG for transparent cutouts

• WebP for opaque assets

• JPEG for flattened web images

• AVIF for aggressive compression

Docs

• Public docs live in docs/public/

• Wiki-ready pages live in docs/wiki/

• Migration notes and setup details are documented there for public release

• The list_image_models, get_provider_status, and get_model_capabilities tools are documented there as part of the release-facing API surface

Troubleshooting

• If withoutbg is not running, enable WITHOUTBG_AUTOSTART=1 or start the daemon manually.

• If the model list looks wrong, set IMAGE_MCP_DEFAULT_MODEL explicitly.

• If image generation fails with provider-specific errors, verify the provider API key in your MCP environment.

• If you need the raw response details, set IMAGE_MCP_DEBUG=1.