comfyui-mcp — the Claude Code plugin for ComfyUI
Claude Code plugin + MCP server for ComfyUI — generate images and video, execute and author workflows, manage models and custom nodes, and edit your live ComfyUI graph from your Claude session (sidebar panel, zero API keys).
Works on macOS, Linux, and Windows. Auto-detects your ComfyUI installation and port.
88 MCP tools | 16 AI skills (Flux · WAN · LTX video · Qwen · Z-Image · model registry · Civitai · node authoring) | 11 slash commands | 4 autonomous agents | 4 hooks
The plugin ships expert skills that grow with every release — model-specific generation guides with curated download URLs, workflow recipes, troubleshooting, and custom-node authoring — so Claude knows the right sampler, CFG, resolution, and model files for each architecture without trial and error.
🚧 Coming soon: the ComfyUI MCP Panel on ComfyUI-Manager & the Comfy Registry
Claude in your ComfyUI sidebar — live graph edits, activity cards, multi-tab, zero API keys. v0.3 is in final testing. Read more →
📖 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.
npxwill 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
# In Claude Code
/plugin marketplace add artokun/comfyui-mcp
/plugin install comfy
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
16 skills total — model-family guides (Flux, WAN, LTX, Qwen, Z-Image), the model-registry (curated download URLs), the civitai pairing skill, node authoring, and the core four below. Full list on the plugin docs page.
| 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_work |