comfyui-mcp

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