Comfyui Mcp

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

[](https://www.npmjs.com/package/comfyui-mcp) [](https://nodejs.org) [](./LICENSE) [](https://comfyui-mcp.artokun.io/docs)

[](https://glama.ai/mcp/servers/artokun/comfyui-mcp) [](https://glama.ai/mcp/servers/artokun/comfyui-mcp)

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

108 MCP tools | 22 AI skills (Flux · WAN · LTX 2.3 video · Qwen · Z-Image · Ideogram 4 · ERNIE · ANIMA · model registry · Civitai · node authoring) | 13 installer packs | 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.

> ### ✅ Now available: the ComfyUI Agent Panel on ComfyUI-Manager & the Comfy Registry > An autonomous AI agent in your ComfyUI sidebar — now on Claude OR ChatGPT (your own subscription, no API key), at full feature parity. Pick a provider and it drives your live graph: edits, spatial layout, one-shot workflow/pack loads, rewind/rollback, a pending-message tray, activity cards, multi-tab — and it asks before spending paid API credits. > Search comfyui-agent-panel in ComfyUI-Manager to install. 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. 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](#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 | Generate an image from a text description — auto-selects checkpoint, builds workflow, returns image | | /comfy:viz | Visualize a workflow as a Mermaid diagram with nodes grouped by category | | /comfy:node-skill | 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 | Parameter sweep generation across cfg, sampler, steps, seed, etc. | | /comfy:convert | Convert between UI format and API format workflows | | /comfy:install | 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 | Diff two workflows side by side — shows added/removed nodes and changed parameters | | /comfy:recipe | Multi-step recipes: portrait, hires-fix, style-transfer, product-shot |

Built-in skills

22 skills total — model-family guides (Flux, WAN, LTX 2.3, Qwen, Z-Image, Ideogram 4, ERNIE, ANIMA + anime / WAN / Z-Image LoRA training), the model-registry (curated download URLs), the civitai pairing skill, node authoring, and the core four below. Full list on the plugin docs page.

> Installer packs. [packs/](packs/) bundles 13 one-command ComfyUI setups — ANIMA, Ideogram 4, LTX-2.3, ERNIE, WAN (animate / longer-videos / transparent), Qwen (image / image-edit), Z-Image (turbo / base / xy-plot) and cozy-flow (AI-influencer video). Each is a manifest of custom nodes + model URLs + workflow that drives both apply_manifest and generated install-windows.bat / install-runpod.sh, with CI that validates every model link + payload size. See [packs/README.md](packs/README.md).

| 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 /comfy:gen a cyberpunk city at night with neon lights

Claude will:
1. Check installed checkpoints (download one if needed)
2. Build a txt2img workflow with your prompt
3. Execute it on ComfyUI
4. Return the generated image

### Visualize a workflow

> /comfy:viz ~/workflows/my-workflow.json

Produces a Mermaid diagram with nodes grouped by category:

```mermaid
flowchart LR
  subgraph Loaders
    1["CheckpointLoaderSimple"]
  end
  subgraph Conditioning
    2(["Positive Prompt"])
    3(["Negative Prompt"])
  end
  subgraph Sampling
    5{{"KSamplersteps:20 cfg:8"}}
  end
  1 -->|MODEL| 5
  2 -->|CONDITIONING| 5
  3 -->|CONDITIONING| 5

Debug a failed workflow

> /comfy:debug

Automatically reads the last execution history and logs, identifies the failing node, checks for missing models or node packs, and suggests a fix.

> /comfy:debug abc123-def456

Diagnose a specific execution by prompt ID.

Parameter sweep

> /comfy:batch a cat in a field, cfg:5-10:2, sampler:euler,dpmpp_2m

Generates a grid of images across all parameter combinations and presents a summary table with results.

Supported sweep parameters: cfg, steps, sampler, scheduler, seed, denoise, width, height.

Multi-step recipes

> /comfy:recipe hires-fix a dramatic fantasy landscape with castles

Runs a two-pass pipeline: txt2img at 512x768, then img2img upscale to 1024x1536 with detail enhancement.

Available recipes:

| Recipe | Description | |--------|-------------| | portrait | Generate at 1024x1024, then 2x upscale to 2048x2048 | | hires-fix | Low-res generation → img2img upscale with denoise 0.4-0.5 | | style-transfer | Apply a style prompt to an existing image via img2img | | product-shot | Product image with clean white background |

Convert workflow format

> /comfy:convert ~/workflows/my-ui-workflow.json

Converts between ComfyUI's UI format (nodes + links arrays) and API format (node IDs → {class_type, inputs}).

Install a custom node pack

> /comfy:install comfyui-impact-pack

Searches the registry, shows details, clones the repo to custom_nodes/, installs dependencies, and offers to restart ComfyUI.

Browse output gallery

> /comfy:gallery last 5
> /comfy:gallery today

Lists recent outputs with embedded metadata — shows checkpoint, prompt, seed, steps, CFG, sampler for each image.

Compare workflows

> /comfy:compare workflow-a.json vs workflow-b.json

Shows added/removed nodes, changed parameters (old → new values), and optional Mermaid diagrams for visual comparison.

Validate before running

> Validate this workflow before I run it

Checks for missing node types, broken connections, invalid output indices, and missing model files — without executing.

Manage models

> What checkpoints do I have installed?
> Search HuggingFace for SDXL turbo models
> Download this model to my checkpoints folder

Manage VRAM

> Free my VRAM
> What embeddings do I have?

Extract workflow from an image

> Extract the workflow from this image: ~/outputs/ComfyUI_00042_.png

Reads the PNG metadata chunks to recover the exact workflow and prompt used to generate the image.

Explore custom nodes

> /comfy:node-skill comfyui-impact-pack

Generates a comprehensive skill file documenting every node, its inputs/outputs, and usage patterns.

Process control

> Restart ComfyUI
> Stop ComfyUI
> Start ComfyUI back up

---

Configuration

The server auto-detects your ComfyUI installation and port. Override with environment variables if needed:

Deployment modes

comfyui-mcp operates in one of three modes, auto-selected from the environment:

| Mode | Trigger | Local FS / process tools? | |------|---------|----------------------------| | Local | default | yes | | Remote | --comfyui-url / COMFYUI_URL points at a non-loopback host | no — server skips COMFYUI_PATH auto-detection so stale local installs can't silently absorb uploads | | Cloud | COMFYUI_API_KEY is set (targets Comfy Cloud) | no — HTTP primitives route via cloud.comfy.org over X-API-Key; WebSocket and local-only tools throw CLOUD_UNSUPPORTED |

| Variable | Default | Description | |----------|---------|-------------| | COMFYUI_URL | | Full ComfyUI URL, e.g. https://comfy.example.com:8443 — overrides COMFYUI_HOST/PORT/SSL and skips auto-detection. A path prefix is preserved (e.g. https://host/comfyapi) for reverse-proxied instances. Non-loopback hosts opt into remote mode. | | COMFYUI_HOST | 127.0.0.1 | ComfyUI server address | | COMFYUI_PORT | (auto-detect) | ComfyUI server port (tries 8188, then 8000) | | COMFYUI_PATH | (auto-detect) | Path to ComfyUI data directory. Auto-detection suppressed in remote/cloud modes. | | COMFYUI_API_KEY | | Comfy Cloud API key. When set, cloud mode is active and the server talks to cloud.comfy.org. Never logged. | | COMFYUI_CLOUD_URL | https://cloud.comfy.org | Override the Comfy Cloud endpoint (testing/staging). | | COMFYUI_AUTH_TOKEN | | Generic auth token for a self-hosted ComfyUI behind a reverse proxy / API gateway (distinct from Comfy Cloud). When set, attached to every ComfyUI request. Never logged. | | COMFYUI_AUTH_HEADER | Authorization | Header name for COMFYUI_AUTH_TOKEN (e.g. X-API-Key). | | COMFYUI_AUTH_SCHEME | Bearer for Authorization, else none | Scheme prefix on the token value (e.g. Bearer, Token). | | CIVITAI_API_TOKEN | | CivitAI API token for model downloads | | HUGGINGFACE_TOKEN | | HuggingFace token for higher API rate limits | | GITHUB_TOKEN | | GitHub token for skill generation (avoids rate limits) | | REGISTRY_ACCESS_TOKEN | | Comfy Registry API key for publish_custom_node (env-only, never logged) | | COMFYUI_DOWNLOAD_CACHE_DIR | ~/.comfyui-mcp/cache | Content-addressed model-download cache (dedup + concurrent coalescing) | | COMFYUI_LRU_CACHE_SIZE_GB | 0 | Cap the download cache in GB; 0 disables LRU eviction | | COMFYUI_STARTUP_CHECK_INTERVAL_S / …_MAX_TRIES | 1 / 20 | Readiness-probe interval + max tries when starting a local ComfyUI | | COMFYUI_ALWAYS_RESTART | false | Auto-restart a crashed local ComfyUI (bounded by COMFYUI_RESTART_MAX_ATTEMPTS / COMFYUI_RESTART_WINDOW_S) | | COMFYUI_MCP_STALL_S | 180 | Render-wedge watchdog: seconds a sampler step can re-emit the same progress before a STALL/BACKLOG note is prepended to the agent's next turn (clamped 15–3600s; live-tunable from the panel) | | COMFYUI_MCP_INTERRUPT_S | 30 | Seconds cancel_job waits for an interrupt to actually stop a job before escalating to /free and reporting it wedged | | LOG_LEVEL | info | Logging verbosity: debug, info, warn, error |

Transports

The server speaks stdio by default (what Claude Code, Claude Desktop, and the MCP Inspector expect — no flags needed). For MCP gateways, remote/hosted setups, or fetch-based clients, opt into streamable-HTTP:

# stdio (default)
npx -y comfyui-mcp

# streamable-HTTP on http://127.0.0.1:9100/mcp
npx -y comfyui-mcp --http
npx -y comfyui-mcp --http --host 0.0.0.0 --port 9100   # bind/port overrides

| Flag | Env | Default | Description | |------|-----|---------|-------------| | --http / --transport http | MCP_TRANSPORT=http | stdio | Serve streamable-HTTP at /mcp instead of stdio | | --host | MCP_HOST | 127.0.0.1 | HTTP bind host (use 0.0.0.0 to expose) | | --port | MCP_PORT | 9100 | HTTP port | | --comfyui-url | COMFYUI_URL | (auto-detect) | Target a specific (incl. remote) ComfyUI |

Remote ComfyUI

Point the server at a ComfyUI running anywhere — no local install required:

npx -y comfyui-mcp --comfyui-url http://192.168.1.50:8188
npx -y comfyui-mcp --http --comfyui-url https://comfy.example.com:8443

Behind a reverse proxy / API gateway (path prefix + auth header) — for a self-hosted ComfyUI exposed under a prefixed route with its own auth layer (this is not Comfy Cloud, which is COMFYUI_API_KEY):

COMFYUI_URL=https://gateway.example.com/comfyapi \
COMFYUI_AUTH_TOKEN=your-token \
  npx -y comfyui-mcp --http        # → Authorization: Bearer your-token, requests under /comfyapi

# custom header / scheme:
COMFYUI_URL=https://gateway.example.com/comfyapi \
COMFYUI_AUTH_HEADER=X-API-Key COMFYUI_AUTH_TOKEN=your-token \
  npx -y comfyui-mcp --http        # → X-API-Key: your-token

Auto-detection

Port: Probes 8188 (CLI default) then 8000 (Desktop app default) via /system_stats.

Path: Checks common locations in order:

• ~/Documents/ComfyUI (macOS/Windows Desktop app data directory)
• ~/Library/Application Support/ComfyUI (macOS)
• ~/AppData/Local/Programs/ComfyUI/resources/ComfyUI (Win

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: artokun
• Source: artokun/comfyui-mcp
• License: MIT
• Homepage: https://comfyui-mcp.artokun.io/docs

Install and usage instructions live in the source repository linked above.