comfyui-mcp

MCP server for ComfyUI. Generate images from natural language prompts using any MCP-compatible client.

Part of the MCP Server Series.

Status

v0.2 — core tools plus upscale, image proxy, and public-URL support. Tools: generate_image, generate_variations, generate_with_workflow, refine_image, upscale_image, list_models, list_workflows, upload_image. See Roadmap for what's next.

Install

npx (no install required)

npx @miller-joe/comfyui-mcp --comfyui-url http://your-comfyui-host:8188

npm

npm install -g @miller-joe/comfyui-mcp
comfyui-mcp --comfyui-url http://your-comfyui-host:8188

Docker

docker run -p 9100:9100 \
  -e COMFYUI_URL=http://your-comfyui-host:8188 \
  ghcr.io/miller-joe/comfyui-mcp:latest

Connect an MCP client

Example — Claude Code:

claude mcp add --transport http comfyui http://localhost:9100/mcp

Or register the streamable HTTP endpoint with an MCP gateway (e.g. MetaMCP) to aggregate with other servers.

Configuration

All options can be set via CLI flag or environment variable:

CLI flag	Env var	Default	Description
--host	MCP_HOST	0.0.0.0	Bind host
--port	MCP_PORT	9100	Bind port
--comfyui-url	COMFYUI_URL	http://127.0.0.1:8188	ComfyUI HTTP URL (used internally by this server to call ComfyUI)
--comfyui-public-url	COMFYUI_PUBLIC_URL	(same as --comfyui-url)	Externally-reachable URL used in image URLs returned to MCP clients. Set this when the internal URL is not reachable from clients (common with Docker networks).
—	COMFYUI_DEFAULT_CKPT	sd_xl_base_1.0.safetensors	Default checkpoint filename

Image URLs returned to clients

Generation tools return image URLs like <comfyui-public-url>/view?filename=…. If --comfyui-public-url is not set, URLs use the internal --comfyui-url value.

The server also exposes a proxy endpoint: GET /images/<filename>?subfolder=&type=output streams the image bytes through the MCP server — useful when clients can reach the MCP server but not ComfyUI directly.

The default checkpoint must match a file installed in your ComfyUI models/checkpoints/ directory. Override via COMFYUI_DEFAULT_CKPT or pass checkpoint as a tool argument.

Tools

generate_image

Generate an image from a text prompt using ComfyUI's default txt2img workflow.

Parameters: prompt (required), negative_prompt, width, height, steps, cfg, seed, checkpoint.

generate_variations

Generate multiple variations of the same prompt by varying the seed. Returns all images at once.

Parameters: prompt (required), count (2–16, default 4), plus the same generation params as generate_image, with base_seed instead of seed.

generate_with_workflow

Submit an arbitrary ComfyUI workflow JSON (full node graph) and return the resulting image URLs. Use this for custom workflows — ControlNet, upscaling, or anything exported from ComfyUI's Save (API Format).

Parameter: workflow (object) — the complete node graph.

refine_image

Run img2img on a source image: fetches a source URL, uploads it to ComfyUI, and runs a denoising pass guided by a new prompt. Lower denoise preserves more of the original; higher gives the prompt more freedom.

Parameters: prompt, source_image_url (required), denoise (0–1, default 0.5), plus standard generation params.

list_models

List available checkpoints, LoRAs, samplers, or schedulers on the ComfyUI instance.

Parameter: kind — one of checkpoints (default), loras, samplers, schedulers.

list_workflows

List built-in workflow templates shipped with this server (currently txt2img, img2img).

upload_image

Upload a reference image to ComfyUI for use in img2img, ControlNet, or IP-Adapter workflows.

Parameters: source_url or image_base64 (one required), filename (optional), overwrite (default false).

Returns: the stored filename, which can be used as the image input in workflow nodes like LoadImage.

generate_with_controlnet

Generate an image conditioned by a ControlNet preprocessed image (pose skeleton, depth map, canny edges, normal map, etc.) plus a text prompt.

Parameters: prompt, control_image_url (the preprocessed conditioning image — this tool doesn't run preprocessors), controlnet_model (filename from models/controlnet/), strength (0–2, default 1), start_percent / end_percent (0–1, when CN is active during sampling), plus standard generation params.

Requires a ControlNet model installed in your ComfyUI models/controlnet/ directory.

generate_with_ip_adapter

Generate an image using a reference image as a visual/style/subject guide via IP-Adapter.

Parameters: prompt, reference_image_url, preset (e.g. "STANDARD (medium strength)", "PLUS FACE (portraits)", "VIT-G (medium strength)"), weight (0–3, default 1), start_at / end_at (0–1), plus standard generation params.

Requires the ComfyUI-IPAdapter-plus custom node pack plus the preset's matching IPAdapter weights and CLIP Vision models.

Workflow template registry

Save complex workflow JSON once, run them by name later. Templates are stored on disk under --templates-dir (defaults to ~/.config/comfyui-mcp/templates/<name>.json) so they survive restarts and are portable across MCP clients.

Tool	Description
save_workflow_template	Save a workflow JSON under a named slot. overwrite=true to replace.
list_workflow_templates	List saved templates with descriptions and last-updated timestamp.
get_workflow_template	Fetch a stored template's JSON + metadata.
delete_workflow_template	Delete a stored template.
run_workflow_template	Run a saved template against ComfyUI and return image URLs.

Template names must start alphanumeric; a-z, A-Z, 0-9, -, _; max 64 chars.

Return format

All generation tools return image URLs served directly by the ComfyUI instance (http://<comfyui>/view?filename=…). These URLs can be passed straight to any client that accepts image URLs.

Architecture

┌────────────────┐     ┌──────────────────┐     ┌──────────────┐
│  MCP client    │────▶│  comfyui-mcp     │────▶│  ComfyUI     │
│  (Claude, etc.)│◀────│  (this server)   │◀────│  instance    │
└────────────────┘     └──────────────────┘     └──────────────┘
     streamable HTTP        HTTP REST + poll

The server is stateless. A single MCP request → submit workflow to ComfyUI → poll /history/{id} until complete → return image URLs.

Development

git clone https://github.com/miller-joe/comfyui-mcp
cd comfyui-mcp
npm install
npm run dev       # hot-reload via tsx watch
npm run build     # compile TS to dist/
npm run typecheck # strict type checking

Requires Node 20+.

Roadmap

• [x] generate_image — text-to-image with default workflow
• [x] generate_with_workflow — submit arbitrary workflows
• [x] list_models / list_workflows
• [x] upload_image — reference images for img2img / ControlNet / IP-Adapter
• [x] generate_variations — batch variations of a prompt
• [x] refine_image — img2img refinement from a source URL
• [x] upscale_image — ESRGAN/SwinIR-style model upscale
• [x] Image proxy endpoint (/images/<filename>) for clients that can't reach ComfyUI
• [x] Configurable public URL for externally-correct image URLs
• [x] Workflow template registry: save_workflow_template, list_workflow_templates, get_workflow_template, delete_workflow_template, run_workflow_template
• [x] ControlNet workflow helper: generate_with_controlnet (requires ControlNet models on the ComfyUI side)
• [x] IP-Adapter workflow helper: generate_with_ip_adapter (requires ComfyUI-IPAdapter-plus pack)
• [ ] WebSocket progress events for long-running generations

License

MIT © Joe Miller

Support

If this tool saves you time, consider supporting development:

Every contribution funds maintenance, documentation, and the next release in the MCP Server Series.