# 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

```bash
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:

```jsonc
{
  "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:

```jsonc
{
  "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:

```jsonc
{
  "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:

```bash
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:

```bash
npm publish
```

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

```bash
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:

```bash
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:

```bash
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`.