comfyui-mcp

comfyui-mcp

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

Status

v0.2 ships the core tools plus upscale, an image proxy, and public-URL support. Current tool surface: generate_image, generate_variations, generate_with_workflow, refine_image, upscale_image, list_models, list_workflows, upload_image, generate_with_controlnet, generate_with_ip_adapter, plus a workflow template registry. 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

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 (HTTP mode only)
--port	MCP_PORT	9100	Bind port (HTTP mode only)
--stdio	MCP_TRANSPORT=stdio	(unset)	Speak MCP over stdio instead of HTTP. Use when launched as a subprocess by a stdio-first MCP client (Claude Desktop, mcp-inspector).
--comfyui-url	COMFYUI_URL	http://127.0.0.1:8188	ComfyUI HTTP URL used internally by this server
--comfyui-public-url	COMFYUI_PUBLIC_URL	same as --comfyui-url	External URL in image URLs returned to clients. Set this when the internal URL is not reachable from MCP clients (common with Docker networks).
(no flag)	COMFYUI_DEFAULT_CKPT	sd_xl_base_1.0.safetensors	Default checkpoint filename

Transports

The server speaks streamable HTTP by default (great for Claude Code, MetaMCP, raw fetch). Pass --stdio (or set MCP_TRANSPORT=stdio) to switch into stdio mode, which is what stdio-first clients like Claude Desktop and the MCP Inspector expect:

# Claude Desktop config (claude_desktop_config.json):
{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["-y", "@miller-joe/comfyui-mcp", "--stdio", "--comfyui-url", "http://127.0.0.1:8188"]
    }
  }
}

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 this server, which is useful when clients can reach the MCP server but not ComfyUI directly.

The default checkpoint must match a file 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. The server 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, upscale, controlnet, ip_adapter).

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, controlling 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 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 plus 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. Allowed: 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 submits a workflow to ComfyUI, polls /history/{id} until complete, and returns 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

Shipped in v0.2:

• generate_image, generate_variations, generate_with_workflow
• refine_image (img2img from a source URL)
• upscale_image (ESRGAN / SwinIR-style model upscale)
• list_models, list_workflows, upload_image
• Image proxy endpoint (/images/<filename>) for clients that can't reach ComfyUI directly
• Configurable public URL for externally-correct image URLs
• Workflow template registry (save/list/get/delete/run)
• generate_with_controlnet (requires ControlNet models on the ComfyUI side)
• generate_with_ip_adapter (requires ComfyUI-IPAdapter-plus pack)

Planned:

• 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.