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.

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

# In Claude Code
/plugin marketplace add artokun/comfyui-mcp
/plugin install comfy

Slash commands

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.

Agents

Hooks

Background Scripts

MCP Tools

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

Image Generation (high-level)

Audio Generation (high-level)

Assets & Iteration

Defaults

Workflow Execution

Workflow Visualization

Workflow Composition

Workflow Validation

Workflow Library

Image Management

Model Management

Memory Management

Registry & Discovery

Diagnostics

Process Control

Generation Tracker

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.

# View local stats from the CLI
npm run generations:stats

Model Settings

Community-maintained preset library (model-settings.json) with research-backed sampler, scheduler, steps, and CFG values for 10+ model families. User overrides in model-settings.user.jsonc (auto-created from template on install, gitignored).

Examples

Generate an image

> /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:

flowchart LR
  subgraph Loaders
    1["CheckpointLoaderSimple"]
  end
  subgraph Conditioning
    2(["Positive Prompt"])
    3(["Negative Prompt"])
  end
  subgraph Sampling
    5{{"KSampler<br/>steps: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:

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:

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

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

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 (Windows Desktop app install)
• ~/AppData/Local/ComfyUI (Windows)
• ~/ComfyUI, ~/code/ComfyUI, ~/projects/ComfyUI, ~/src/ComfyUI
• /opt/ComfyUI, ~/.local/share/ComfyUI (Linux)
• Scans ~/Documents and ~/My Documents for any directory containing "ComfyUI"

Set COMFYUI_PATH to skip detection and use an explicit path.

How It Works

The server communicates with ComfyUI through its REST API and WebSocket interface:

• WebSocket — enqueue workflows, receive real-time progress updates (step-by-step via background monitor script), get execution results
• REST API — system stats, node definitions (/object_info), logs, history, queue management, workflow library, VRAM control (/free), embeddings
• File system — read/write models directory, detect installation paths, upload images, extract PNG metadata, browse outputs
• External APIs — HuggingFace (model search), ComfyUI Registry (custom node discovery), GitHub (skill generation), CivitAI (model downloads)

All communication with the MCP client (Claude Code) happens over stdio using the Model Context Protocol. Logs go to stderr to avoid polluting the protocol stream.

Development

Prerequisites

• Node.js >= 22.0.0
• ComfyUI running locally

Setup

git clone https://github.com/artokun/comfyui-mcp.git
cd comfyui-mcp
npm install

Scripts

Local testing with Claude Code

Point Claude Code at your local build instead of the npm package:

{
  "mcpServers": {
    "comfyui": {
      "command": "node",
      "args": ["/path/to/comfyui-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Or test the plugin directly:

claude --plugin-dir ./plugin

Project structure

model-settings.json            # Community-maintained model presets (shipped)
model-settings.user.jsonc.example  # User override template (copied on install)
scripts/
  postinstall.mjs              # Auto-creates user config from template
  generation-stats.mjs         # CLI: npm run generations:stats
src/
  index.ts                 # MCP server entry point (stdio transport)
  config.ts                # Auto-detection & environment config
  comfyui/
    client.ts              # ComfyUI WebSocket/HTTP client wrapper
    types.ts               # TypeScript interfaces
  services/
    workflow-executor.ts   # Execute workflows, handle images & errors
    workflow-composer.ts   # Templates (txt2img, img2img, upscale, inpaint)
    workflow-validator.ts  # Dry-run validation (missing nodes, models, connections)
    image-management.ts    # Upload images, extract PNG metadata, list outputs
    mermaid-converter.ts   # Workflow → Mermaid diagram
    mermaid-parser.ts      # Mermaid diagram → Workflow
    model-resolver.ts      # HuggingFace search, local models, downloads
    generation-tracker.ts  # SQLite generation log, settings dedup, stats
    file-hasher.ts         # SHA256 hashing of .safetensors with cache
    civitai-lookup.ts      # CivitAI API lookup by content hash
    workflow-settings-extractor.ts  # Extract settings from workflow JSON
    process-control.ts     # Stop, start, restart ComfyUI process
    registry-client.ts     # ComfyUI Registry API
    skill-generator.ts     # Generate node pack skill docs
  tools/                   # MCP tool registration (one file per group)
    workflow-execute.ts    # enqueue_workflow, get_system_stats
    workflow-visualize.ts  # visualize_workflow, mermaid_to_workflow
    workflow-compose.ts    # create_workflow, modify_workflow, get_node_info
    workflow-validate.ts   # validate_workflow
    workflow-library.ts    # list_workflows, get_workflow, save_workflow
    image-management.ts    # upload_image, workflow_from_image, list_output_images
    model-management.ts    # search_models, download_model, list_local_models
    memory-management.ts   # clear_vram, get_embeddings
    registry-search.ts     # search_custom_nodes, get_node_pack_details
    skill-generator.ts     # generate_node_skill
    generation-tracker.ts  # suggest_settings, generation_stats
    diagnostics.ts         # get_logs, get_history
    process-control.ts     # stop_comfyui, start_comfyui, restart_comfyui
    index.ts               # Registers all tool groups
  utils/
    errors.ts              # Custom error hierarchy with MCP integration
    logger.ts              # stderr-only logging (safe for stdio transport)
    image.ts               # Base64 encoding utilities
plugin/
  .claude-plugin/          # Plugin manifest
  .mcp.json                # MCP server config for plugin
  commands/                # Slash commands
    gen.md                 # /comfy:gen — image generation
    viz.md                 # /comfy:viz — workflow visualization
    node-skill.md          # /comfy:node-skill — skill generation
    debug.md               # /comfy:debug — failure diagnosis
    batch.md               # /comfy:batch — parameter sweeps
    convert.md             # /comfy:convert — format conversion
    install.md             # /comfy:install — node pack installation
    gallery.md             # /comfy:gallery — output browser
    compare.md             # /comfy:compare — workflow diff
    recipe.md              # /comfy:recipe — multi-step pipelines
  skills/                  # Knowledge bases
    comfyui-core/          # Workflow format, node types, pipeline patterns
    prompt-engineering/    # CLIP syntax, model-specific prompting
    troubleshooting/       # Error catalog with patterns and fixes
    model-compatibility/   # Compatibility matrix per model family
  agents/                  # Autonomous agents
    explorer.md            # Research custom node packs, generate skills
    debugger.md            # Diagnose workflow failures
    optimizer.md           # Analyze and optimize workflows
  hooks/                   # Pre/post tool-use hooks
    hooks.json             # Hook configuration
    vram-check.mjs         # VRAM watchdog before execution
    save-warning.mjs       # Save prompt before stop/restart
    job-complete-notify.mjs # Job completion notification via temp files
  scripts/                 # Background scripts
    monitor-progress.mjs   # Real-time WebSocket progress monitor

Troubleshooting

"ComfyUI not detected on ports 8188, 8000" Make sure ComfyUI is running. The Desktop app uses port 8000 by default; the CLI uses 8188. Set COMFYUI_PORT if you're using a custom port.

"COMFYUI_PATH is not configured" The auto-detection couldn't find your ComfyUI data directory. Set COMFYUI_PATH to the directory containing your models/ folder (e.g., ~/Documents/ComfyUI).

"Multiple ComfyUI installations detected" This is informational — the server uses the first one found. Set COMFYUI_PATH to pick a specific installation.

Model downloads fail For HuggingFace gated models, set HUGGINGFACE_TOKEN. For CivitAI, set CIVITAI_API_TOKEN.

Workflow execution errors Use /comfy:debug to automatically diagnose failures. Or use get_history / get_logs directly to see detailed error messages including Python tracebacks from ComfyUI.

Out of memory (OOM) Use clear_vram to free GPU memory before running large workflows. The VRAM watchdog hook will warn you automatically if memory is critically low. See the troubleshooting skill for model-specific VRAM estimates.

Missing custom nodes Use /comfy:install <pack> to install missing node packs from the registry. The debug command will detect and suggest missing packs automatically.

Contributing

Contributions are welcome! See CONTRIBUTING.md for the dev setup, project conventions, how to add an MCP tool, and the release process.

Quick version: fork → branch (feat/my-feature) → make changes (ensure npm run build and npm test pass; run npm run docs:gen if you touched tools) → open a PR.

Maintainer

Built and maintained by @artokun — a regular contributor across the Comfy-Org ecosystem:

• Comfy-Org/ComfyUI_frontend — 10 merged PRs, mostly on the v2 graph renderer: subgraph rendering, promoted-widget plumbing, viewport persistence, with backports across cloud/1.41, cloud/1.42, core/1.41, and core/1.42.
• Comfy-Org/ComfyUI (core) — crash fixes in the Python backend's video/audio save path (#12683, #12550).

Comfy-Org folks (or anyone hiring around the ComfyUI ecosystem): I'd genuinely love to chat — art.longbottom.jr@gmail.com.

License

MIT — see LICENSE for details.

Changelog

The full, structured changelog lives in CHANGELOG.md. Recent highlights:

0.9.1 – 0.9.5 — 2026-06-01 → 2026-06-11

Stability + interop + paperwork. Five patch releases tightening the rough edges around 0.9.0:

• 0.9.5 — federation-friendly: resources/list / prompts/list / resources/templates/list now return empty arrays (with matching resources / prompts capability declarations) so federating clients like LiteLLM don't pay a per-server timeout probing capabilities we don't expose. MIT LICENSE file added at the repo root. Both reported by @ductiletoaster.
• 0.9.4 — Glama build fix: disabled .d.ts emission (TS2742 portability error under pnpm; we're a CLI, not a library).
• 0.9.3 — llms-install.md agent-focused install guide + 400×400 marketplace logo, both for the Cline MCP Marketplace listing.
• 0.9.2 — Docker build fix: skip the cloudflared postinstall binary fetch that hung on rate-limited CI (Glama). Runtime tunnel helper still downloads it lazily on first use.
• 0.9.1 — get_job_status now routes through cloud-client.getJobStatus in cloud mode. Refined CLOUD_UNSUPPORTED message (no longer leaks internal function name). vitest 3 → 4 (clears GHSA-5xrq-8626-4rwp, dev-only).

0.9.0 — 2026-06-01

Comfy Cloud + remote mode + slim install.

• Comfy Cloud — set COMFYUI_API_KEY to route HTTP-backed primitives to cloud.comfy.org with X-API-Key auth. Architecture and dispatcher pattern ported with attribution from @picoSols's comfyui-cloud-mcp fork.
• Smart-detect remote mode — --comfyui-url at a non-loopback host suppresses COMFYUI_PATH auto-detection, closing the root cause of the 0.8.1 upload-fallback bug.
• isCloudMode() / isRemoteMode() / isLocalMode() config helpers + new "Deployment modes" docs section.
• Slim install — seven heavy/feature-gated packages (@aws-sdk/*, @azure/*, cloudflared, ai, @ai-sdk/*) moved to optionalDependencies with lazy dynamic-imports; missing deps now surface OPTIONAL_DEP_MISSING with the exact npm install hint.

0.8.1 — 2026-06-01

Upstream fork picks (with attribution to @joaolvivas).

• health_check — single-call pre-flight diagnostic (version, GPU/VRAM, queue, per-category /models populations, recent /internal/logs errors).
• search_custom_nodes fix — api.comfy.org/nodes was ignoring the search param server-side; now fetches a larger window and rank-filters client-side.
• upload_image / upload_video / upload_audio HTTP-only — removed the deceptive filesystem fallback that silently misrouted uploads when COMFYUI_PATH auto-detected a stale local install.

0.8.0 — 2026-05-26

Lifecycle + I/O + discovery.

• apply_manifest — declarative env setup (pip / custom_nodes / models) from an inline or JSON/YAML manifest; idempotent.
• verify_custom_node — restart + /object_info load-check that a scaffolded/installed pack's node types actually registered.
• scaffold_custom_node — now also emits .comfyignore/.gitignore and (with with_ci) a GitHub publish workflow.
• convert_image — re-encode outputs to PNG/JPEG/WebP via sharp.
• Cloud storage — s3:// / Azure-Blob model downloads + a new upload_output (S3/Azure/HTTP/HF).
• comfy-researcher agent — problem → ranked custom-node recommendations; generate_node_skill is now cached (source@version).
• Security — pip/argv-injection guards, realpath/symlink-safe path containment, cloud-credential + SAS/presigned redaction, redirect-SSRF hardening.

0.7.0 — 2026-05-25

Stability + authoring.

• Custom-node authoring — scaffold_custom_node (template a Python node pack) and publish_custom_node (publish to the Comfy Registry; REGISTRY_ACCESS_TOKEN).
• install_custom_node ref pinning — pin to a commit/branch/tag (URL ref or explicit ref).
• download_model auth — per-request bearer/basic/header/query auth for gated/private models.
• Download cache — content-addressed dedup + concurrent coalescing + optional LRU (COMFYUI_DOWNLOAD_CACHE_DIR, COMFYUI_LRU_CACHE_SIZE_GB).
• Process supervision — bounded startup readiness checks + opt-in bounded crash auto-restart for local installs.
• Actionable failures — get_job_status / completion now surface ComfyUI execution errors (OOM, traceback, node) and per-node + total timing.
• Security — download-auth input validation + secret redaction; git-ref argv-injection hardening; spawn error listeners so a bad executable can't crash the server.
• Experimental — flag-gated embedded-agent backend POC (cloudflared tunnel + AI SDK chat).
• Docs — hosted Mintlify site with a schema-generated tool reference.

0.6.1 — 2026-05-25

• upload_video / upload_audio — copy local video/audio files into ComfyUI's input directory so they can be referenced as workflow inputs, mirroring upload_image.

0.6.0 — 2026-05-25

comfy-cli capability port — much of the comfy-cli workflow is now exposed as MCP tools, preferring the ComfyUI-Manager HTTP API with a subprocess fallback:

• Custom nodes — install_custom_node, update_custom_node, reinstall_custom_node, fix_custom_node, list_installed_nodes, sync_node_dependencies.
• Node snapshots — save_node_snapshot, restore_node_snapshot, list_node_snapshots.
• Node bisect — bisect_start, bisect_good, bisect_bad, bisect_reset, bisect_status to isolate a faulty custom node.
• Workflow dependencies — extract_workflow_dependencies, install_workflow_dependencies (API- and UI-format workflows).
• Install / update — install_comfyui, update_comfyui, update_all.
• Models — remove_model (path-safe) and download_civitai_model.
• Workspace & environment — get_workspace, set_default_workspace, list_workspaces, get_environment.
• API / partner nodes — list_api_nodes, get_api_node_schema, generate_with_api_node.
• ComfyUI-Manager config — configure_manager.
• Security — CivitAI auth moved to an Authorization: Bearer header (token no longer leaks into logs/URLs); model-download filenames validated against path traversal; COMFY_API_KEY delivered via the /prompt extra_data payload rather than the workflow.
• Rewrote core tool/parameter descriptions for clearer agent tool-selection; added a Dockerfile and the Glama listing.

0.5.0 — 2026-05-21

• Streamable-HTTP transport — opt in with --http (or MCP_TRANSPORT=http) to serve MCP over HTTP at /mcp for gateways, remote, and fetch-based clients. stdio remains the default; --host/--port configure the bind.
• Remote ComfyUI — --comfyui-url / COMFYUI_URL targets any (incl. remote) ComfyUI instance, overriding host/port/ssl and skipping auto-detection.
• generate_with_controlnet — ControlNet-conditioned generation (pose/depth/canny/normal) from a control image + prompt.
• generate_with_ip_adapter — reference-image style/subject guidance via IP-Adapter (requires ComfyUI_IPAdapter_plus).
• Two new create_workflow templates: controlnet, ip_adapter.

0.4.1 — 2026-05-21

• Added server.json and an mcpName field to package.json for publishing to the official MCP Registry (io.github.artokun/comfyui-mcp).

0.4.0 — 2026-05-20

Iteration & convenience tools — closing the generate → see → iterate loop:

• generate_image — high-level entry point. Build a txt2img workflow from just a prompt; every unspecified parameter is filled from your configured defaults, and a local checkpoint is auto-selected when none is given. Returns a prompt_id immediately; the resulting asset_id arrives in the completion notification.
• Asset registry — every generated output gets a stable asset_id, backed by an in-memory store that keeps the workflow snapshot for reproduction. TTL configurable via COMFYUI_ASSET_TTL_HOURS (default 24h). The registry is ephemeral and clears on server restart.
• view_image — fetch a registered asset's bytes and return them as an inline image so the agent can see the result. Supports PNG/JPEG/WebP.
• regenerate — re-run the workflow that produced an asset, with optional parameter overrides (cfg, steps, sampler_name, seed, text, …). Seeds re-randomize by default; pass seed + disable_random_seed to reproduce exactly.
• list_assets / get_asset_metadata — browse recent assets newest-first and inspect full provenance including the originating workflow.

Auto-exposed workflows — drop a workflow JSON into COMFYUI_WORKFLOWS_DIR (default ~/.comfyui-mcp/workflows) and it registers as its own typed MCP tool at startup. Mark inputs with PARAM_PROMPT, PARAM_INT_<NAME>, PARAM_FLOAT_<NAME>, PARAM_STRING_<NAME>, or PARAM_BOOL_<NAME>. Invalid JSON is logged and skipped, never fatal.

Configurable defaults — stop repeating common settings:

• get_defaults — merged view with per-source attribution.
• set_defaults — update the runtime layer, or pass persist: true to write the config file (~/.config/comfyui-mcp/config.json).
• Resolution precedence (lowest → highest): config file → COMFYUI_DEFAULT_* env vars → runtime overrides → per-call arguments.