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.
31 MCP tools | 10 slash commands | 4 knowledge skills | 3 autonomous agents | 3 hooks
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.
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
artokun