comfy-image-mcp

An MCP server that turns your own ComfyUI workflows into an image-generation tool for any MCP client: Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI, Gemini CLI and others. ComfyUI can run on the same machine or on a GPU box elsewhere on your LAN. You need no API key and pay nothing per image.

The server exposes two tools:

• generate_image runs a txt2img, reference-edit or background-removal workflow. It writes the PNG and a <out>.json prompt sidecar into your project, and also returns the image to the client.

• image_backend_status reports whether ComfyUI is reachable, the GPU and free VRAM, which workflows are configured, and which directory images are written to.

Machine running your MCP client                       GPU machine
┌─────────────────────────────────────┐   HTTP :8188  ┌────────────────────────┐
│ MCP client (Claude Code, Cursor, …) │               │ ComfyUI                │
│   └─ generate_image ───────────────┐│ ────────────▶ │  txt2img.json          │
│      (comfy-image-mcp, stdio)      ││  /prompt      │  edit.json   (refs)    │
│   ◀─ PNG + sidecar in project,─────┘│  /upload      │  cutout.json (alpha)   │
│      image in the tool result       │ ◀──────────── │                        │
└─────────────────────────────────────┘  /view        └────────────────────────┘

1. Set up ComfyUI

The walkthrough below uses a Windows PC with an NVIDIA GPU as the GPU machine. If ComfyUI runs on the same machine as your MCP client, skip step 1.4 and use http://127.0.0.1:8188.

1.1 Install ComfyUI

1. Update the GPU driver.

2. Download ComfyUI Windows Portable (NVIDIA) from the ComfyUI GitHub releases and extract it to a short path such as C:\ComfyUI. ComfyUI Desktop and Linux installs work too. The only difference is where you set the listen address (step 1.4).

3. Run run_nvidia_gpu.bat once, then open http://127.0.0.1:8188 to confirm it starts.

4. Use a recent ComfyUI release. The shipped workflows rely on core nodes that older versions don't have: the switch nodes, TextEncodeQwenImageEditPlus, and the background-removal nodes. You don't need any custom nodes.

1.2 Download the models

The workflows in workflows/ are API exports of ComfyUI's Qwen-Image 2512 and Qwen-Image-Edit 2511 templates. They need these files:

The easiest way to get them is from ComfyUI itself: open Workflow → Browse Templates, then the Qwen-Image 2512 and Qwen-Image-Edit 2511 templates. Each template lists its models and offers to download them into the right folders. Generate one image in the UI before you continue.

Both workflows ship with the Lightning 4-step LoRA switched off. txt2img runs 30 steps at CFG 4, and edit runs 40 steps at CFG 4. To use the LoRA, set the Enable 4 Steps LoRA? boolean to true in the JSON, which gives 4 steps at CFG 1. ComfyUI checks every model name in a workflow, so keep the LoRA files installed even while the switch is off.

Each diffusion model is about 20 GB in fp8. On a 24 GB card only one fits in VRAM at a time, so the first call after switching between plain generation and reference edits is slower while ComfyUI swaps models.

Other models work as well. Export your own workflow (section 2) and point the server at it. Some options as of 2026 (this area moves fast):

1.3 Check the result

Run each workflow once in the ComfyUI UI. A missing model file shows up there as a red node. Through the server, it shows up as rejected the workflow (400).

1.4 Make ComfyUI reachable from the LAN (remote GPU only)

1. Add the listen flags to the python line in run_nvidia_gpu.bat:

   .\python_embeded\python.exe -s ComfyUI\main.py --windows-standalone-build --listen 0.0.0.0 --port 8188

   In ComfyUI Desktop, go to Settings → Server-Config → Host 0.0.0.0.

2. Give both machines fixed addresses, for example with a DHCP reservation on the router. The examples below use 192.168.1.50 for the GPU machine and 192.168.1.20 for the client machine.

3. ComfyUI has no authentication, so open the port only to the client machine. Run this in an admin PowerShell:

   New-NetFirewallRule -DisplayName "ComfyUI (MCP client only)" -Direction Inbound -Protocol TCP `
     -LocalPort 8188 -RemoteAddress 192.168.1.20 -Profile Private -Action Allow

   Make sure the Windows network profile is Private, and never port-forward 8188 on the router.

4. Keep the PC from sleeping while you work.

Related MCP server: comfyui-mcp

2. Workflows

The server reads up to three API-format workflows from COMFY_WORKFLOWS_DIR. By default that is the workflows/ folder shipped with the package.

workflows/examples/qwen-image.txt2img.json is a smaller hand-written graph for the original Qwen-Image model (qwen_image_fp8_e4m3fn.safetensors). It's a useful starting point if you write your own.

To use your own workflows, copy the shipped ones (or export new ones) into a folder of your own and set COMFY_WORKFLOWS_DIR to that folder. Don't edit them inside node_modules.

Exporting a workflow

Open the workflow in ComfyUI and choose Workflow → Export (API). Then open the JSON in an editor and replace the relevant values with placeholders:

A placeholder that makes up a whole value, such as "{{WIDTH}}", is replaced with a real number, so numeric fields stay numeric. Any unknown {{…}} placeholder is an error.

How the shipped workflows behave:

• txt2img.json has a fixed Chinese negative prompt (taken from the template) and no {{NEGATIVE}}.

• edit.json has two reference slots, and sizes its output from the first reference (FluxKontextImageScale), so size is ignored. The tool always reports the size it actually got.

• cutout.json uses the core Remove Background node with BiRefNet, then joins the inverted mask back on as alpha.

3. Install

You need Node.js 22 or later.

npx -y comfy-image-mcp        # what MCP clients run; it waits on stdin, so Ctrl-C to exit

To work on it, or to smoke-test against your ComfyUI first, use a clone instead. This needs Node 22.18 or later, because the dev scripts run the .ts sources directly.

git clone <this repo> comfy-image-mcp && cd comfy-image-mcp
npm install
npm test                      # offline end-to-end test against a mock ComfyUI

export COMFYUI_URL=http://192.168.1.50:8188
npm run status
npm run gen -- --prompt "SaaS landing page hero, editorial serif headline \"Ship calmer\", warm off-white" \
  --out tmp/test.png --size 1536x1024
npm run gen -- --prompt "friendly paper-cut fox mascot" --out tmp/fox.png --size 1024x1024 --background transparent

In a clone, a client can also run node /path/to/comfy-image-mcp/src/server.ts instead of npx -y comfy-image-mcp.

4. Connect your MCP client

Every client needs the same three things: the command npx -y comfy-image-mcp, COMFYUI_URL, and a project root (below). The snippets use 192.168.1.50. Replace it with your own address, or with 127.0.0.1 if ComfyUI runs locally.

Where images are written

out and refs are paths relative to a project root, and the server refuses paths outside it. The root is picked in this order:

1. COMFY_PROJECT_ROOT, if set.

2. The first file:// root the client reports through MCP roots, if the client supports them.

3. The directory the client started the server in.

If that ends up being / (Claude Desktop, for example, starts servers there), the server refuses to write and asks for COMFY_PROJECT_ROOT. Use image_backend_status to see which root is in effect.

Claude Code

claude mcp add comfy-image --scope user \
  -e COMFYUI_URL=http://192.168.1.50:8188 \
  -e COMFY_MODEL_LABEL=qwen-image-2512 \
  -- npx -y comfy-image-mcp

claude mcp list               # comfy-image should show as connected

Claude Code starts the server in the directory you launched claude from, so outputs land in that project. Start claude from the project root.

Claude Desktop

Edit claude_desktop_config.json (Settings → Developer → Edit Config). Claude Desktop doesn't start servers in a project directory, so set the root explicitly:

{
  "mcpServers": {
    "comfy-image": {
      "command": "npx",
      "args": ["-y", "comfy-image-mcp"],
      "env": {
        "COMFYUI_URL": "http://192.168.1.50:8188",
        "COMFY_PROJECT_ROOT": "/home/you/Pictures/comfy"
      }
    }
  }
}

The image comes back in the tool result, so it shows in the chat.

Cursor

.cursor/mcp.json in the project, or ~/.cursor/mcp.json for all projects:

{
  "mcpServers": {
    "comfy-image": {
      "command": "npx",
      "args": ["-y", "comfy-image-mcp"],
      "env": {
        "COMFYUI_URL": "http://192.168.1.50:8188",
        "COMFY_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

VS Code (Copilot agent mode)

.vscode/mcp.json:

{
  "servers": {
    "comfy-image": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "comfy-image-mcp"],
      "env": {
        "COMFYUI_URL": "http://192.168.1.50:8188",
        "COMFY_PROJECT_ROOT": "${workspaceFolder}"
      }
    }
  }
}

Codex CLI

~/.codex/config.toml:

[mcp_servers.comfy-image]
command = "npx"
args = ["-y", "comfy-image-mcp"]
env = { COMFYUI_URL = "http://192.168.1.50:8188" }
tool_timeout_sec = 600

Gemini CLI

.gemini/settings.json in the project, or ~/.gemini/settings.json:

{
  "mcpServers": {
    "comfy-image": {
      "command": "npx",
      "args": ["-y", "comfy-image-mcp"],
      "env": { "COMFYUI_URL": "http://192.168.1.50:8188" },
      "timeout": 600000
    }
  }
}

Other clients

Any client that can launch a stdio MCP server works with the same command and environment. Two things to check:

• Root. If image_backend_status shows the wrong project root, set COMFY_PROJECT_ROOT.

• Timeout. A cold model load plus a large image can take a minute or two, and many clients give up on a tool call after about 60 s by default. Raise the client's tool timeout to around 10 minutes: MCP_TOOL_TIMEOUT=600000 for Claude Code, tool_timeout_sec for Codex, timeout for Gemini CLI. While a job runs, the server sends MCP progress notifications whenever the client asks for them, and some clients use those to keep the call alive.

Optional: tell the agent about it

Most agents find the tool from its description. A short note in your project's agent instructions (AGENTS.md, CLAUDE.md, .cursor/rules, …) still helps:

## Image generation
- Use `generate_image` (comfy-image MCP, local ComfyUI) for mockups, illustrations and other raster assets.
  Pass `refs` for reference-guided edits and `background: "transparent"` for cutouts.
- It is slow (~20–120 s) and free; generate one image at a time. Check `image_backend_status` if a call fails.
- Local models garble small text: describe layout, hierarchy, palette and type character; keep quoted copy to headlines.

In Claude Code, you can skip the permission prompt on every call by adding this to .claude/settings.json or ~/.claude/settings.json:

{
  "permissions": {
    "allow": ["mcp__comfy-image__generate_image", "mcp__comfy-image__image_backend_status"]
  }
}

Reference

Tools

generate_image({ prompt, out, size?, refs?, background?, seed?, negative? })

The result has a text summary (path, size, workflow, seed, notes) and the PNG as an MCP image block, as long as the PNG is no larger than COMFY_INLINE_MAX_BYTES. Next to the image the server writes <out>.json:

{
  "prompt": "…",
  "createdAt": "2026-10-24T12:00:00.000Z",
  "tool": "comfy-image-mcp",
  "model": "qwen-image-2512",
  "workflow": "txt2img",
  "seed": 123456789,
  "size": "1536x1024",
  "background": "auto"
}

negative and refs are added to it when you use them. The PNG also carries ComfyUI's own embedded workflow metadata.

image_backend_status() reports the ComfyUI version, the GPU and free VRAM, which workflows are present, and the project root. It doesn't generate anything.

Environment

Troubleshooting

License

MIT. See LICENSE.