ComfyUI MCP

What is ComfyUI MCP about?

ComfyUI MCP provides a full‑featured MCP server plus a sidebar agent that can interact with a running ComfyUI instance. It enables LLMs such as Claude, ChatGPT, Gemini, Ollama or any OpenAI‑compatible endpoint to generate media, compose and modify node graphs, install custom node packs, and manage model files—all through natural‑language prompts or slash commands.

How to use ComfyUI MCP?

1. Install ComfyUI (desktop app or source).
2. Add the MCP server to your Claude Code (or any MCP‑compatible client) using the npx command:

{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["-y", "comfyui-mcp"],
      "env": { "CIVITAI_API_TOKEN": "" }
    }
  }
}

3. Start ComfyUI.
4. Ask the LLM (e.g., Claude) to generate an image, edit a graph, install a node pack, etc.
5. For remote or cloud deployments, run the server with flags such as --http, --tunnel, or --comfyui-url <URL>.

Key Features

• 182 MCP tools covering generation, workflow execution, model management, diagnostics, and process control.
• 36 AI skills (Flux, WAN, LTX 2.3, Qwen, Ideogram 4, ERNIE, ANIMA, etc.) that provide model‑specific prompts and workflow recipes.
• 55 installer packs that auto‑install custom nodes, download required checkpoints, and load ready‑to‑run workflows.
• Panel Agent: an autonomous sidebar AI (Claude, ChatGPT, Gemini, Ollama, etc.) that edits the live graph, rolls back changes, and shows a pending‑message tray.
• Multi‑provider LLM support – Claude, ChatGPT, Gemini, Ollama, OpenRouter, DeepSeek, GLM, Kimi, etc.
• Local‑first design – runs on macOS, Linux or Windows without internet; optional remote/VPN/RunPod mode.
• LLM Arena – built‑in benchmark that scores every supported model on real ComfyUI tasks.
• VRAM watchdog & cost guardrails – pre‑execution hooks warn when GPU memory is low and ask before spending paid API credits.
• Workflow visualisation (Mermaid diagrams) and bi‑directional conversion between UI and API formats.
• Audio generation (ACE Step 1.5, Stable Audio 3) and video generation (Flux, WAN, LTX, etc.).

Use Cases

• Creative media production – generate high‑quality images, animations or music from a single textual prompt.
• Rapid prototyping – ask an LLM to create or modify a ComfyUI workflow on the fly, then instantly run it.
• Model & node management – search HuggingFace, download checkpoints, install custom node packs, and keep the library up‑to‑date.
• Remote GPU pods – drive a RunPod, VPS or LAN‑hosted ComfyUI from a local machine without installing any agent on the remote host.
• Cost‑controlled automation – run batch sweeps, schedule jobs, and let the VRAM watchdog prevent out‑of‑memory crashes.
• Educational tooling – the built‑in skills and troubleshooting guides let newcomers learn prompt engineering and workflow debugging.

FAQ

Q: Which operating systems are supported?
A: macOS, Linux and Windows are all supported. The server auto‑detects the ComfyUI installation and port.

Q: Do I need an internet connection?
A: No. When using a local model via Ollama (or any offline checkpoint) the whole stack runs offline. Internet is only required for remote model APIs or model downloads.

Q: How do I run the server against a remote ComfyUI instance?
A: Use the --comfyui-url flag (or set COMFYUI_URL). Example: npx -y comfyui-mcp@latest --comfyui-url https://my‑pod.runpod.net. For a public tunnel add --tunnel.

Q: Can I limit API spending?
A: Yes. The check_workflow_runtime tool classifies whether a workflow will use paid API nodes and the panel prompts the user before any credit‑consuming call.

Q: How do I configure environment variables for model downloads?
A: Set CIVITAI_API_TOKEN, HUGGINGFACE_TOKEN or GITHUB_TOKEN in your environment; they are read automatically by the server.

Q: What if I have multiple ComfyUI installations?
A: The auto‑detector picks the first match. To force a specific location set COMFYUI_PATH.

Q: Is there a lightweight mode for non‑Claude agents?
A: Yes. Use npx -y comfyui-mcp setup <agent> (e.g., hermes, openclaw, copilot) and optionally --compact to register only three meta‑tools.

comfyui-mcp — drive ComfyUI with ANY LLM

The local-first, agent-native control plane for ComfyUI — an MCP server + live sidebar agent that generates images, video and audio, authors and runs workflows, manages models and custom nodes, and edits your live ComfyUI graph in natural language. Bring whatever model you have: Claude or ChatGPT on your subscription, Gemini on your Google login, a free local model via Ollama (fully offline), or any hosted model over one API key (DeepSeek, GLM, MiMo, Kimi, GPT, Claude via OpenRouter). Same tools, same panel, every tier — and the built-in LLM Arena scores them all on real ComfyUI tasks so you know exactly what your model can do. One config targets local installs, LAN, VPS, or Comfy Cloud.

 One-click GPU pod — a ready-to-run ComfyUI with this project + Agent Panel + ComfyUI-Manager v2 preinstalled, on your own GPU. No setup.

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

Stuck or have a question? Join the Discord — help, model tips, and release announcements.

182 MCP tools | 36 AI skills (Flux · WAN · LTX 2.3 video · Qwen · Z-Image · Ideogram 4 · ERNIE · ANIMA · model registry · Civitai · node authoring · launch/perf flags) | 55 installer packs | 11 slash commands | 4 autonomous agents | 3 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 — on Claude, ChatGPT, Gemini, or ANY local/hosted LLM (Ollama and every OpenAI-compatible endpoint). Subscriptions work with no API key; local models work with no account at all. 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 local-first: a self-hosted ComfyUI on Mac/Linux/Windows is the primary target, with the same agent reaching remote installs (RunPod, VPS, LAN, reverse-proxied) from one config. Local-first, not local-only.

More than a bridge. Most ComfyUI MCP servers are thin connectors — they forward a prompt and hand back an image. comfyui-mcp is a full control plane: it authors and edits the graph node-by-node, runs and iterates on workflows, manages models and custom nodes, and ships model-specific expertise (samplers, CFG, resolutions, curated model URLs) so the agent gets it right without trial and error. If you want a minimal local relay, a lightweight server is fine; if you want an agent that actually operates ComfyUI, that's this project.

For Comfy Cloud users, Comfy-Org ships its own agent tooling: Comfy Cloud MCP (public beta, hosted on Comfy Cloud GPUs), the Comfy In-App Agent (private alpha, inside Comfy Cloud), and a first-party Comfy Local MCP (private test, not publicly available yet) — all maintained by the Comfy team. If you don't have a GPU or you want zero setup, that's the better path; go use it.

Where this project differs is that it runs on your install and your choice of model — including a free local one via Ollama with no account and no network at all. 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.

📊 Local vs. Comfy Cloud agent — an honest side-by-side, including when Comfy Cloud is the right answer. (Statuses above are as of July 2026; Comfy-Org ships fast — check their docs for the current state.)

Remote / hosted connector (one command)

Want to use comfyui-mcp from Claude Desktop's Custom Connectors or any remote client — like Comfy's own cloud.comfy.org/mcp connector? Run it as an authenticated, publicly-reachable Streamable-HTTP server with one flag:

npx -y comfyui-mcp@latest --tunnel

This forces the HTTP transport, generates an auth token, opens a cloudflared quick tunnel, and prints a ready-to-paste https://…/mcp URL + token + Claude Desktop connector snippet. Auth accepts Authorization: Bearer <token> or X-API-Key: <token> (matching Comfy Cloud's convention). See the Remote / hosted connector guide for the full walkthrough and headless usage.

Auth is opt-in: with no COMFYUI_MCP_HTTP_TOKEN set and no --tunnel, the default stdio (and plain --http on loopback) behavior is unchanged — open and local. OAuth (Comfy's browser sign-in flow) is a planned follow-up.

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

35 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, the launch/performance-flags matrix, and the core four below. Full list on the plugin docs page.

Installer 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 artokun-flow (WAN Animate — replace / animate). 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.

Agents

Hooks

Background Scripts

Panel agent (Claude · ChatGPT · Gemini · any local/hosted LLM)

Beyond the headless MCP server, this package ships the panel orchestrator that powers the ComfyUI Agent Panel — an autonomous agent embedded in ComfyUI's sidebar that drives the live canvas. It runs in the background on your own subscription (Claude or ChatGPT), started on demand by the panel's Connect button:

npx -y comfyui-mcp@latest connect

Drive a REMOTE ComfyUI from your own machine (connect)

When ComfyUI runs somewhere with no Node/agent (a RunPod pod, a cloud box) you can still run the agent on your machine and drive that remote ComfyUI — no agent login on the box, nothing to install or configure remotely:

npx -y comfyui-mcp@latest connect https://abcd1234-8188.proxy.runpod.net

This is sugar for --panel-orchestrator with COMFYUI_URL set from the URL: the orchestrator runs locally on your Claude/ChatGPT login and reaches the remote ComfyUI over its public proxy URL. For a remote HTTPS pod, connect automatically opens a secure, token-gated wss:// tunnel (via Cloudflare) to the local agent bridge and hands the pod's panel that URL — so the pod's HTTPS page reaches your machine with no browser prompt, in any browser (a secure page can't open a plain ws:// socket to your box — mixed content / Private Network Access). A local ComfyUI uses the plain ws://127.0.0.1:9180 loopback bridge; add --insecure-bridge to force that loopback for a remote pod (then arrange your own path to it, e.g. an SSH port-forward). Either way the panel JS runs in your local browser and the agent — and your login — run only on your machine, so nothing is installed remotely.

To finish: open the remote ComfyUI in your browser, turn on Settings → General → "Use external/local orchestrator (advanced)" in the Agent panel, then click Connect. (In that mode the panel connects straight to the local bridge instead of asking the ComfyUI host to spawn an orchestrator it can't run.)

Multi-provider, full parity. The orchestrator depends on a provider-neutral AgentBackend port (dependency injection), with two adapters:

• ClaudeBackend — the Claude Agent SDK (@anthropic-ai/claude-agent-sdk), a persistent streaming session over the claude.ai subscription (OAuth, no key).
• CodexBackend — OpenAI Codex over the codex app-server JSON-RPC protocol (@openai/codex), on the ChatGPT subscription (codex login, no key).

Further adapters follow the same port — Gemini CLI (ACP), Antigravity (agy, the Google AI Pro/Ultra subscription path — install from antigravity.google and run agy once to sign in), Grok, Kimi, GLM, Ollama/LM Studio/llama.cpp (local), OpenRouter, and any OpenAI-compatible endpoint. See docs/backends for the full matrix.

Both are optional dependencies, and the panel picks a provider, not a port — each backend runs its own orchestrator on its own loopback bridge port. A capability matrix lets the panel degrade gracefully (e.g. conversation-rollback is Claude-only today, since the Codex app-server resumes whole threads only).

The live-canvas tools and model knowledge are identical across providers. The panel_* tool definitions live in one shared list, registered onto both the in-process Claude SDK MCP server and a @modelcontextprotocol/sdk server over a loopback streamable-HTTP MCP that the orchestrator hosts for Codex (which can only host config-declared MCP servers). The headless comfyui MCP is likewise injected into both — in-process for Claude, declared via codex app-server -c mcp_servers for ChatGPT — so generation, models, and workflow tools are the same everywhere.

New tools that give every backend the same expertise and a cost guardrail:

See the design doc — docs/design/agent-backend-injection.md — for the port, the capability matrix, and the per-provider "clink" points, and the panel docs for the full sidebar UX.

MCP Tools

182 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

Official comfy-cli

Install comfy-cli 1.11.1 or newer to enable the official JSON-backed tools. The MCP resolves comfy from COMFY_CLI_PATH, PATH, or the selected workspace's .venv/venv. Local custom-node operations prefer comfy node when a supported CLI is available and otherwise fall back to Manager HTTP; remote targets retain Manager HTTP.

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:

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.

Where to put keys and overrides:

• Panel users: the API Keys card (▾ menu next to "connected") — stored in ~/.comfyui-mcp/panel-secrets.json, applied immediately, no restart.
• MCP-only setups (Claude Desktop, Claude Code, etc.): the env block of your MCP client config, as shown in the setup examples above.
• Real environment variables always take precedence over stored keys. (For development, ~/.comfyui-mcp/.env is also loaded as an override file — regular installs shouldn't need it.)

Deployment modes

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

Some setups (e.g. dstack driving ComfyUI on RunPod) port-forward a remote ComfyUI back to localhost:8188, so the loopback check above gets it wrong — the install isn't actually local. Pass --force-remote (or set COMFYUI_MCP_FORCE_REMOTE=1) alongside --comfyui-url/COMFYUI_URL to force remote mode regardless of hostname:

npx -y comfyui-mcp@latest --comfyui-url http://localhost:8188 --force-remote

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@latest

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

Other agents & local LLMs (Hermes, OpenClaw, Copilot CLI, Ollama)

comfyui-mcp has first-class support for non-Claude harnesses. One command writes the server entry into the harness's own config (merging, not clobbering):

npx -y comfyui-mcp setup hermes     # → ~/.hermes/config.yaml      (compact by default)
npx -y comfyui-mcp setup openclaw   # → ~/.openclaw/openclaw.json  (compact by default)
npx -y comfyui-mcp setup copilot    # → ~/.copilot/mcp-config.json (full by default)
# flags: --compact | --full, --comfyui-url <url>, --dry-run

Model requirements: tool calling is a hard requirement (no tool calling = doesn't work). Thinking and vision are strongly recommended — without thinking, multi-step tool chains degrade; without vision the agent can generate but can't see its own outputs.

For small/local models, compact tool mode (--compact / COMFYUI_MCP_TOOL_MODE=compact) registers 3 meta-tools (list_tools → describe_tool → call_tool) instead of the full ~200-schema surface, pulling schemas into context one tool at a time. Run it locally for free with our fine-tuned models: ollama pull artokun/gemma4-comfyui-mcp:e4b (also :e2b for ~2 GB VRAM, :12b for ~8 GB) — Gemma 4 QLoRA-trained on 1,055 server-verified trajectories over the full comfyui-mcp tool surface, and the panel's Ollama default. Stock gemma4:*/qwen3:4b also validated end-to-end (npm run test:local-llm); gemma3 has no native tool calling and is unsupported. Full guide — hosted-model guidance (DeepSeek/MiMo/GLM class), per-harness setup, troubleshooting: Local LLMs & other agents.

Other agents & local LLMs (Hermes, OpenClaw, Copilot CLI, Ollama)

comfyui-mcp has first-class support for non-Claude harnesses. One command writes the server entry into the harness's own config (merging, not clobbering):

npx -y comfyui-mcp setup hermes     # → ~/.hermes/config.yaml      (compact by default)
npx -y comfyui-mcp setup openclaw   # → ~/.openclaw/openclaw.json  (compact by default)
npx -y comfyui-mcp setup copilot    # → ~/.copilot/mcp-config.json (full by default)
# flags: --compact | --full, --comfyui-url <url>, --dry-run

Model requirements: tool calling is a hard requirement (no tool calling = doesn't work). Thinking and vision are strongly recommended — without thinking, multi-step tool chains degrade; without vision the agent can generate but can't see its own outputs.

For small/local models, compact tool mode (--compact / COMFYUI_MCP_TOOL_MODE=compact) registers 3 meta-tools (list_tools → describe_tool → call_tool) instead of the full ~200-schema surface, pulling schemas into context one tool at a time. Run it locally for free with our fine-tuned models: ollama pull artokun/gemma4-comfyui-mcp:e4b (also :e2b for ~2 GB VRAM, :12b for ~8 GB) — Gemma 4 QLoRA-trained on 1,055 server-verified trajectories over the full comfyui-mcp tool surface, and the panel's Ollama default. Stock gemma4:*/qwen3:4b also validated end-to-end (npm run test:local-llm); gemma3 has no native tool calling and is unsupported. Full guide — hosted-model guidance (DeepSeek/MiMo/GLM class), per-harness setup, troubleshooting: Local LLMs & other agents.

Remote ComfyUI

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

npx -y comfyui-mcp@latest --comfyui-url http://192.168.1.50:8188
npx -y comfyui-mcp@latest --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@latest --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@latest --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 (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
    workflow-converter.ts  # UI → API: de-virtualize Get/Set buses + Reroutes, expand subgraphs, resolve bypass (powers strip_workflow)
    workflow-slicer.ts     # sliceWorkflow() — rgthree Fast-Groups-Bypass pipeline un-chunker (shared by the CLI + slice_workflow)
    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, strip_workflow, slice_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

See CHANGELOG.md for the full, structured release history.