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

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.

| Client | Use built-in app image models directly? | What works | |---|---|---| | Cursor | No | Point IMAGE_MCP_LOCAL_ENDPOINT at a local image server or bridge | | Claude Code | No | Point IMAGE_MCP_LOCAL_ENDPOINT at a local image server or bridge | | Codex | No | Point IMAGE_MCP_LOCAL_ENDPOINT at a local image server or bridge | | MLX / local server | Yes, if exposed as an endpoint | Set IMAGE_MCP_LOCAL_PROVIDER=mlx or openai-compatible |

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.

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.