comfyui-mcp

MCP server + Claude Code plugin for ComfyUI — execute workflows, generate images, visualize pipelines, manage models, control VRAM, and explore custom nodes, all from your AI coding assistant.

Works on macOS, Linux, and Windows. Auto-detects your ComfyUI installation and port.

80+ MCP tools | 10 slash commands | 6 knowledge skills | 3 autonomous agents | 3 hooks

📖 Full documentation: comfyui-mcp.artokun.io/docs

---

Quick Start

1. Install ComfyUI (if you haven't already): ComfyUI Desktop or from source

2. Add the MCP server to your Claude Code config (~/.claude/settings.json):

{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["-y", "comfyui-mcp"],
      "env": {
        "CIVITAI_API_TOKEN": ""
      }
    }
  }
}

3. Start using it. With ComfyUI running, ask Claude to generate an image:

> Generate an image of a sunset over mountains

Claude will find (or download) a checkpoint, build a workflow, execute it, and return the image.

> Note: This runs as a standalone MCP server — no need to clone this repo. npx will download and run it automatically.

Scope: local, remote, or Comfy Cloud

comfyui-mcp is the community MCP for local and remote ComfyUI (Mac/Linux/Windows installs, RunPod, VPS, LAN, etc.) — that's the primary target.

For Comfy Cloud users, Comfy-Org ships an official Comfy Cloud MCP (currently invite-only beta) which is cloud-exclusive and maintained by the Comfy team. comfyui-mcp also includes a community cloud-mode (set COMFYUI_API_KEY — see Deployment modes) so a single MCP can target all three deployment shapes from one config; pick whichever fits your workflow.

---

Claude Code Plugin

This package also ships as a Claude Code plugin, providing slash commands, skills, agents, and hooks on top of the MCP tools.

Install as a plugin

claude plugin install comfyui-mcp

Slash commands

| Command | Description |
|---------|-------------|
| /comfy:gen <prompt> | Generate an image from a text description — auto-selects checkpoint, builds workflow, returns image |
| /comfy:viz <workflow> | Visualize a workflow as a Mermaid diagram with nodes grouped by category |
| /comfy:node-skill <pack> | Generate a Claude skill for a custom node pack from Registry ID or GitHub URL |
| /comfy:debug [prompt_id] | Diagnose why a workflow failed — reads history, logs, traces root cause, suggests fixes |
| /comfy:batch <prompt, params> | Parameter sweep generation across cfg, sampler, steps, seed, etc. |
| /comfy:convert <file> | Convert between UI format and API format workflows |
| /comfy:install <pack> | Install a custom node pack — git clone, pip install, optional restart |
| /comfy:gallery [filter] | Browse generated outputs with metadata — filter by date, count, or filename |
| /comfy:compare <a vs b> | Diff two workflows side by side — shows added/removed nodes and changed parameters |
| /comfy:recipe <name> <prompt> | Multi-step recipes: portrait, hires-fix, style-transfer, product-shot |

Built-in skills

| Skill | Description |
|-------|-------------|
| comfyui-core | Workflow format, node types, data flow patterns, pipeline architecture, MCP tool usage guide |
| prompt-engineering | CLIP weight syntax (word:1.3), BREAK tokens, embeddings, model-specific prompting for SD1.5/SDXL/Flux/SD3 |
| troubleshooting | Common error catalog — OOM, dtype mismatches, missing nodes, NaN tensors, black images, CUDA errors, with VRAM estimates per model |
| model-compatibility | Compatibility matrix — loaders, resolutions, CFG, samplers, ControlNets, LoRAs, and VAEs per model family (SD1.5/SDXL/Turbo/Lightning/Flux/SD3/LTXV) |

Agents

| Agent | Model | Description |
|-------|-------|-------------|
| comfy-explorer | Sonnet | Researches custom node packs — reads docs, queries /object_info, generates comprehensive skill files |
| comfy-debugger | Sonnet | Autonomously diagnoses workflow failures — gathers logs + history, identifies failing node, checks models + custom nodes, proposes and optionally applies fixes |
| comfy-optimizer | Sonnet | Analyzes workflows for performance — detects redundant nodes, VRAM waste, wrong CFG/steps for model family, precision issues, suggests optimizations |

Hooks

| Event | Trigger | Action |
|-------|---------|--------|
| PreToolUse | enqueue_workflow | VRAM watchdog — checks GPU memory via /system_stats and warns if < 1GB free before execution |
| PreToolUse | stop_comfyui, restart_comfyui | Save warning — prompts user to save unsaved workflow changes before stopping ComfyUI |
| PostToolUse | Any comfyui tool | Job completion notify — checks for completed jobs and injects completion summaries into the conversation |

Background Scripts

| Script | Description |
|--------|-------------|
| monitor-progress.mjs | Progress monitor — connects to ComfyUI's WebSocket for real-time step progress (e.g., step 5/14 (36%)). Run as a background Bash task after enqueuing workflows. Reports completion with output filenames, errors with node details. Replaces polling get_job_status in a loop. |

---

MCP Tools

46 tools across workflow execution, generation, iteration, composition, models, and more:

Image Generation (high-level)

| Tool | Description |
|------|-------------|
| generate_image | Generate from a text prompt — builds a txt2img workflow, fills unspecified params from your defaults, auto-selects a checkpoint |
| generate_with_controlnet | Generate conditioned by a ControlNet image (pose/depth/canny/normal) + prompt |
| generate_with_ip_adapter | Generate guided by a reference image's style/subject via IP-Adapter (needs ComfyUI_IPAdapter_plus) |

Assets & Iteration

| Tool | Description |
|------|-------------|
| view_image | Return a generated asset's bytes as an inline image so the agent can see the result |
| regenerate | Re-run the workflow that produced an asset_id, with optional parameter overrides |
| list_assets | Browse recently generated assets (newest-first) by asset_id |
| get_asset_metadata | Full provenance for an asset, including the originating workflow |

Defaults

| Tool | Description |
|------|-------------|
| get_defaults | Show merged generation defaults with per-source attribution |
| set_defaults | Update runtime defaults; persist: true writes the config file |

Workflow Execution

| Tool | Description |
|------|-------------|
| enqueue_workflow | Submit a workflow (API format JSON) — returns prompt_id immediately, non-blocking |
| get_job_status | Check execution status of a job by prompt ID |
| get_queue | View the current execution queue (running + pending) |
| cancel_job | Interrupt the currently running job |
| get_system_stats | Get system info — GPU, VRAM, Python version, OS |

Workflow Visualization

| Tool | Description |
|------|-------------|
| visualize_workflow | Convert a workflow to a Mermaid flowchart with nodes grouped by category |
| mermaid_to_workflow | Convert a Mermaid diagram back to executable workflow JSON |

Workflow Composition

| Tool | Description |
|------|-------------|
| create_workflow | Generate a workflow from templates: txt2img, img2img, upscale, inpaint |
| modify_workflow | Apply operations: set_input, add_node, remove_node, connect, insert_between |
| get_node_info | Query available node types from ComfyUI's /object_info endpoint |

Workflow Validation

| Tool | Description |
|------|-------------|
| validate_workflow | Dry-run validation — checks missing nodes, broken connections, invalid output indices, missing model files |

Workflow Library

| Tool | Description |
|------|-------------|
| list_workflows | List saved workflows from ComfyUI's user library |
| get_workflow | Load a specific saved workflow by filename |
| save_workflow | Save a workflow to the ComfyUI user library |

Image Management

| Tool | Description |
|------|-------------|
| upload_image | Copy a local image into ComfyUI's input/ directory for img2img, inpaint, or ControlNet |
| workflow_from_image | Extract embedded workflow metadata from a ComfyUI-generated PNG (reads prompt and workflow tEXt chunks) |
| list_output_images | Browse recently generated images from the output directory, sorted newest-first |

Model Management

| Tool | Description |
|------|-------------|
| search_models | Search HuggingFace for compatible models (checkpoints, LoRAs, VAEs, etc.) |
| download_model | Download a model from a URL to the correct ComfyUI subdirectory |
| list_local_models | List installed models by type: checkpoints, loras, vae, upscale_models, controlnet, embeddings, clip, unet |

Memory Management

| Tool | Description |
|------|-------------|
| clear_vram | Free GPU VRAM by unloading cached models — calls ComfyUI's /free endpoint, reports before/after stats |
| get_embeddings | List installed textual inversion embeddings |

Registry & Discovery

| Tool | Description |
|------|-------------|
| search_custom_nodes | Search the ComfyUI Registry for custom node packs by keyword |
| get_node_pack_details | Get full details of a custom node pack (description, author, nodes, install info) |
| generate_node_skill | Generate a Claude skill .md file from a Registry ID or GitHub URL |

Diagnostics

| Tool | Description |
|------|-------------|
| get_logs | Get ComfyUI server logs with optional keyword filter (e.g., error, warning, a node name) |
| get_history | Get execution history with full error details, Python tracebacks, timing, and cached node info |

Process Control

| Tool | Description |
|------|-------------|
| stop_comfyui | Stop the running ComfyUI process (saves PID and launch args for restart) |
| start_comfyui | Start ComfyUI using info saved from a previous stop |
| restart_comfyui | Stop and restart ComfyUI, preserving all launch arguments |

Generation Tracker

| Tool | Description |
|------|-------------|
| suggest_settings | Suggest proven sampler/scheduler/steps/CFG settings from local generation history — query by model family, LoRA hash, or text search |
| generation_stats | Show local generation tracking statistics — total runs, unique combos, breakdown by model family |

Every enqueue_workflow call automatically logs settings to a local SQLite database (generations.db). Same settings combos get a reuse_count bump instead of duplicates, creating a natural popularity signal. Models and LoRAs are identified by content hash (AutoV2 / SHA256), not filenames — so renamed files still group together.

```bash