{"id":"5818d84e-3881-4973-a0a9-3eab7bc14987","slug":"img-gen-mcp","kind":"mcp","name":"img-gen-mcp","summary":"MCP server for image generation, local image manipulation, and web-ready finalization through compatible providers.","owner":"jgkme","repoUrl":"https://github.com/jgkme/img-gen-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":3,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-06-09T06:52:28.000Z","addedAt":"2026-10-21T17:31:56.274Z","logoUrl":"https://avatars.githubusercontent.com/u/60567291?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["design-media","cloud-infra"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-26T04:07:20.695Z","sample":false,"url":"https://conduits.dev/tools/img-gen-mcp","language":"JavaScript","transports":["stdio"],"install":{"npm":"img-gen-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# img-gen-mcp\n\n`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.\n\nIt 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.\n\nIt combines:\n- OpenRouter-first image generation\n- Kilo Gateway support\n- OpenAI and Gemini image generation\n- provider auto-selection and model-driven routing\n- async task submission and polling\n- batch image generation for prompt sweeps and variants\n- local image generation through OpenAI-compatible endpoints and local bridges for MLX, ComfyUI, Draw Things, and llama.cpp-compatible servers\n- Streamable HTTP transport for remote deployments\n- optional ACP-style HTTP automation routes layered on top of MCP\n- local background cleanup with `rmbg`, `imgly`, and a shared Docker-backed `withoutbg` daemon\n- web optimization with `sharp`\n- deterministic prompt enhancement before generation\n\n## Features\n\n- `generate_image` for OpenRouter-first generation with response normalization\n- `kilo_generate_image` for Kilo Gateway routing\n- provider auto-selection through `provider=auto` or model-driven inference\n- `list_image_models` for provider/model discovery with warnings and capability hints\n- `get_provider_status` for backend readiness and local bootstrap guidance\n- `get_model_capabilities` for a compact capability summary\n- `edit_image` for prompt-driven image editing\n- local provider support for OpenAI-compatible endpoints and local bridges like MLX, ComfyUI, and Draw Things\n- `submit_task` and `get_task` for async generation workflows\n- `batch_generate_image` for running multiple prompts in one request\n- `create_workflow`, `update_workflow`, `get_workflow`, and `finalize_workflow` for iterative interactive jobs\n- `add_workflow_step` and `close_workflow_step` for explicit workflow lifecycle tracking\n- `resume_workflow` for continuing a persisted workflow after restart\n- `analyze_image_result` and `suggest_next_step` for image-backed follow-up guidance\n- `inspect_cutout` and `compare_variants` for specialized analysis helpers\n- `background_remove` for local cutouts and the shared local withoutBG daemon\n- `resize_image` and `auto_crop` for deterministic local transforms\n- `optimize_image` for web-ready re-encoding and compression\n- `finalize_image` for a one-call local workflow that can remove background, trim, crop, and resize\n- alpha stats and multi-background inspection sheets for post-processing QA\n- prompt enhancement before generation\n- automatic web optimization after background removal/finalize\n- debug mode via `IMAGE_MCP_DEBUG=1`\n\n## Release Notes\n\n- Workflow records are now persisted to `.image-mcp-workflows.json` and can be resumed after restart.\n- `add_workflow_step` and `close_workflow_step` are available for explicit workflow lifecycle tracking.\n- `analyze_image_result` and `suggest_next_step` now inspect the actual image file for structured guidance.\n\n## Asset Workflows\n\nFor SVG-style icons, logos, favicons, and game sprites, use the built-in asset workflow guidance in `docs/public/asset-workflows.md`.\n\nThat keeps the repository self-contained for npm/GitHub users without asking them to install extra marketplace skills.\n\n## Install\n\n```bash\nnpm install -g img-gen-mcp\n```\n\nIf 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`.\n\n## Configuration\n\nUse the correct launch command for your setup:\n\n- Local checkout: `node /absolute/path/to/img-gen-mcp/server.js`\n- Published package: `npx -y img-gen-mcp`\n- HTTP transport: `npx -y img-gen-mcp http`\n\nSet these environment variables in your MCP client:\n\n- `IMAGE_MCP_DEFAULT_PROVIDER` - default provider when none is supplied\n- `IMAGE_MCP_DEFAULT_MODEL` - default model when none is supplied\n- `IMAGE_MCP_PROJECT_OUTPUT_DIR` - optional project-specific output root\n- `IMAGE_MCP_DEFAULT_BG_BACKEND` - default local cleanup backend (`rmbg`, `imgly`, or `withoutbg`)\n- `WITHOUTBG_DAEMON_URL` - local daemon URL, defaults to `http://127.0.0.1:8765`\n- `WITHOUTBG_AUTOSTART=1` - auto-start the shared withoutBG Docker daemon on demand\n- `IMAGE_MCP_DEFAULT_BG_ALPHA_THRESHOLD` - tighter default mask for logos/header assets\n- `IMAGE_MCP_PROMPT_ENHANCE=0` - disable deterministic prompt enhancement\n- `IMAGE_MCP_DEBUG=1` - include detailed tool errors and provider payloads\n\nLocal model environment variables:\n\n- `IMAGE_MCP_LOCAL_PROVIDER` - selects `openai-compatible`, `comfyui`, `drawthings`, or `mlx`\n- `IMAGE_MCP_LOCAL_ENDPOINT` - local HTTP base URL\n- `IMAGE_MCP_LOCAL_MODEL` - local model slug\n- `IMAGE_MCP_LOCAL_AUTOSTART=1` - opt-in local service startup\n- `IMAGE_MCP_LOCAL_BOOTSTRAP=1` - opt-in bootstrap helper mode\n- `IMAGE_MCP_LOCAL_TIMEOUT_MS` - request timeout for local endpoints\n- `IMAGE_MCP_LOCAL_API_KEY` - optional local auth token\n\nTransport and runtime flags:\n\n- `IMAGE_MCP_TRANSPORT=http` - opt in to Streamable HTTP transport\n- `IMAGE_MCP_HTTP_HOST` - host for HTTP transport, defaults to `127.0.0.1`\n- `IMAGE_MCP_HTTP_PORT` - port for HTTP transport, defaults to `3333`\n- `IMAGE_MCP_ACP=1` - enable the optional ACP-style automation surface on HTTP transport\n- `IMAGE_MCP_ACP_PATH` - ACP route prefix, defaults to `/acp`\n\nExample MCP config for a local checkout:\n\n```jsonc\n{\n  \"mcp\": {\n    \"img-gen-mcp\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"img-gen-mcp\"],\n      \"enabled\": true,\n      \"environment\": {\n        \"IMAGE_MCP_DEFAULT_PROVIDER\": \"openrouter\",\n        \"IMAGE_MCP_DEFAULT_MODEL\": \"openai/gpt-image-1\",\n        \"IMAGE_MCP_DEFAULT_BG_BACKEND\": \"imgly\",\n        \"WITHOUTBG_DAEMON_URL\": \"http://127.0.0.1:8765\",\n        \"WITHOUTBG_AUTOSTART\": \"1\"\n      }\n    }\n  }\n}\n```\n\nExample MCP config for the published package:\n\n```jsonc\n{\n  \"mcp\": {\n    \"img-gen-mcp\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"img-gen-mcp\"],\n      \"enabled\": true,\n      \"environment\": {\n        \"IMAGE_MCP_DEFAULT_PROVIDER\": \"openrouter\",\n        \"IMAGE_MCP_DEFAULT_MODEL\": \"openai/gpt-image-1\",\n        \"IMAGE_MCP_DEFAULT_BG_BACKEND\": \"imgly\",\n        \"WITHOUTBG_DAEMON_URL\": \"http://127.0.0.1:8765\",\n        \"WITHOUTBG_AUTOSTART\": \"1\"\n      }\n    }\n  }\n}\n```\n\nLocal examples:\n\n```jsonc\n{\n  \"mcp\": {\n    \"img-gen-mcp\": {\n      \"type\": \"local\",\n      \"command\": [\"npx\", \"-y\", \"img-gen-mcp\"],\n      \"enabled\": true,\n      \"environment\": {\n        \"IMAGE_MCP_LOCAL_PROVIDER\": \"mlx\",\n        \"IMAGE_MCP_LOCAL_ENDPOINT\": \"http://127.0.0.1:8000/v1\",\n        \"IMAGE_MCP_LOCAL_MODEL\": \"qwen3.5\",\n        \"IMAGE_MCP_LOCAL_AUTOSTART\": \"1\"\n      }\n    }\n  }\n}\n```\n\nSee `docs/public/clients.md` for ready-to-use examples for Kilo, Cursor, and generic MCP clients.\n\n## ACP Automation\n\n`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.\n\nEnable it with:\n\n```bash\nIMAGE_MCP_TRANSPORT=http IMAGE_MCP_ACP=1 npm start\n```\n\nRoute overview:\n\n- `GET /acp/health`\n- `GET /acp/agent`\n- `GET /acp/tools`\n- `POST /acp/tools/:tool_name`\n- `POST /acp/tasks`\n- `GET /acp/tasks/:task_id`\n- `POST /acp/tasks/:task_id/cancel`\n- `POST /acp/workflows`\n- `GET /acp/workflows/:workflow_id`\n- `POST /acp/workflows/:workflow_id/steps`\n- `PATCH /acp/workflows/:workflow_id/steps/:step_id`\n- `POST /acp/workflows/:workflow_id/finalize`\n\nThe 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.\n\nThe package ships bundled skills under `skills/` so other users can reuse the same workflow guidance when they install the package or browse the repository.\n\nUse `npm run test:acp` to smoke-test the ACP routes locally.\n\n## Published Package\n\nThe package version is `0.11.0`.\n\nAfter this release is published to GitHub, you can publish to npm manually with:\n\n```bash\nnpm publish\n```\n\nIf you want to verify the release artifact first, run:\n\n```bash\nnpm pack --dry-run\n```\n\n## Guidance\n\n- Use `provider=auto` when you want the server to infer the backend from a model slug.\n- Use `submit_task` for long-running generations when your client prefers polling.\n- Use `batch_generate_image` when you want multiple prompt variants without reconfiguring the client.\n- Use `get_provider_status` before troubleshooting a local runtime so you can see the expected endpoint and startup hint.\n- Use `IMAGE_MCP_LOCAL_BOOTSTRAP=1` when you want the server to print setup guidance for the configured local adapter.\n- 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.\n- Run the workflow persistence regression test with `npm run test:workflow`.\n\nWorkflow tools:\n\n- `create_workflow`\n- `update_workflow`\n- `get_workflow`\n- `resume_workflow`\n- `finalize_workflow`\n- `analyze_image_result`\n- `inspect_cutout`\n- `compare_variants`\n- `suggest_next_step`\n\n## App Model Access\n\n`img-gen-mcp` cannot automatically use the image models built into Cursor, Claude Code, or Codex.\n\nIt can only use a model source that is exposed to it as a separate provider or local HTTP endpoint.\n\n| Client | Use built-in app image models directly? | What works |\n|---|---|---|\n| Cursor | No | Point `IMAGE_MCP_LOCAL_ENDPOINT` at a local image server or bridge |\n| Claude Code | No | Point `IMAGE_MCP_LOCAL_ENDPOINT` at a local image server or bridge |\n| Codex | No | Point `IMAGE_MCP_LOCAL_ENDPOINT` at a local image server or bridge |\n| MLX / local server | Yes, if exposed as an endpoint | Set `IMAGE_MCP_LOCAL_PROVIDER=mlx` or `openai-compatible` |\n\nIf 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.\n\nFor 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.\n\n## Workflow\n\nThe typical pipeline is:\n\n1. Generate an image\n2. Remove background if needed\n3. Inspect the cutout on multiple backgrounds\n4. Optimize the final asset for the web\n5. Save and ship the final PNG/WebP/JPEG/AVIF\n\nFor 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.\n\n## Common Uses\n\n- logos\n- icons\n- header artwork\n- product photography\n- realistic subject cutouts\n- transparent PNG delivery\n\n## Models\n\nSupported OpenRouter image models include:\n- `microsoft/mai-image-2.5`\n- `openai/gpt-image-1`\n- `openai/gpt-5-image-mini`\n- `openai/gpt-5.4-image-2`\n- `x-ai/grok-imagine-image-quality`\n- `google/gemini-2.5-flash-image`\n- `google/gemini-2.5-flash-image-preview`\n- `google/gemini-3-pro-image-preview`\n- `sourceful/riverflow-v2.5-fast`\n- `sourceful/riverflow-v2.5-pro`\n- `sourceful/riverflow-v2.5-fast:free`\n- `sourceful/riverflow-v2-fast`\n- `sourceful/riverflow-v2-pro`\n- `recraft/recraft-v4.1-utility`\n- `recraft/recraft-v4.1-vector`\n- `recraft/recraft-v4.1-utility-pro`\n- `recraft/recraft-v4.1-pro-vector`\n- `recraft/recraft-v3`\n- `black-forest-labs/flux.2-pro`\n- `black-forest-labs/flux.2-flex`\n\nRecommended defaults:\n- Photorealistic work: `microsoft/mai-image-2.5` or `openai/gpt-image-1`\n- Quick stylized work: `x-ai/grok-imagine-image-quality`\n- Logos / vector-like work: `recraft/recraft-v4.1-vector`\n- Broad prompt-following general use: `sourceful/riverflow-v2.5-pro`\n\n## Local backends\n\n- `openai-compatible` for any `/v1`-style local server\n- `mlx` for macOS local model wrappers\n- `comfyui` for workflow-driven generation\n- `drawthings` for a running macOS app bridge\n- `llama.cpp` for a lightweight local OpenAI-compatible endpoint\n\n## Background Removal Backends\n\n- `rmbg` - fastest lightweight local cleanup\n- `imgly` - higher-quality local cleanup\n- `withoutbg` - shared Docker-backed local daemon for harder edges, fur, and transparent cutouts\n\nStart the shared daemon once:\n\n```bash\ndocker compose -f withoutbg-daemon/docker-compose.yml up -d\n```\n\nIf `WITHOUTBG_AUTOSTART=1` is set, the MCP will try to start it automatically when `backend=withoutbg` is used.\n\nIf the MCP runs inside another container and the `withoutbg` daemon runs on the host, point the MCP at the host-published port:\n\n```bash\nWITHOUTBG_DAEMON_URL=http://host.docker.internal:8765\n```\n\nOn 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`.\n\n## Web Optimization\n\n`background_remove` and `finalize_image` automatically run a web optimization pass after cleanup.\n\nUse `optimize_image` directly when you want explicit control:\n- PNG for transparent cutouts\n- WebP for opaque assets\n- JPEG for flattened web images\n- AVIF for aggressive compression\n\n## Docs\n\n- Public docs live in `docs/public/`\n- Wiki-ready pages live in `docs/wiki/`\n- Migration notes and setup details are documented there for public release\n- The `list_image_models`, `get_provider_status`, and `get_model_capabilities` tools are documented there as part of the release-facing API surface\n\n## Troubleshooting\n\n- If `withoutbg` is not running, enable `WITHOUTBG_AUTOSTART=1` or start the daemon manually.\n- If the model list looks wrong, set `IMAGE_MCP_DEFAULT_MODEL` explicitly.\n- If image generation fails with provider-specific errors, verify the provider API key in your MCP environment.\n- If you need the raw response details, set `IMAGE_MCP_DEBUG=1`.\n"}