The local-first, agent-native control plane for ComfyUI. An MCP server plus a live sidebar agent that generates images, video and audio, authors and runs workflows, manages models and custom nodes, and . Bring whatever model you have: (DeepSeek, GLM, MiMo, Kimi, GPT, Claude via OpenRouter). The tools and the panel are the same on every tier, and the built-in scores each model on real ComfyUI tasks so you know what yours can do. One config targets local installs, LAN, VPS, or Comfy Cloud.
Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no API key), free local models via Ollama (fully offline),
2026-11-15
星标
—
工具
—
可用率
—
edits your live ComfyUI graph in natural language
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
The plugin ships skills that grow with every release: model-specific generation guides with curated download URLs, workflow recipes, troubleshooting, and custom-node authoring. With them, 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, running 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. It asks before spending paid API credits.
Search comfyui-agent-panel in ComfyUI-Manager to install. Read more →
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, so there is no need to clone this repo. npx downloads and runs it.
Scope: local, remote, or Comfy Cloud
comfyui-mcp is local-first. A self-hosted ComfyUI on Mac/Linux/Windows is the primary target, and the same agent reaches 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 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-mcpalso 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 is a side-by-side comparison, including when Comfy Cloud is the right answer. (Statuses above are as of July 2026. Comfy-Org ships fast, so check their docs for the current state.)
Remote / hosted connector (one command)
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. It stays 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 that adds 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 <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
42 skills total: model-family guides (Flux, WAN, LTX 2.3, MiniMax H3, 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.
Skill
Description
comfyui-core
Workflow format, node types, data flow patterns, pipeline architecture, MCP tool usage guide
Analyzes workflows for performance — detects redundant nodes, VRAM waste, wrong CFG/steps for model family, precision issues, suggests optimizations
comfy-researcher
Sonnet
Discovers and ranks ComfyUI custom node packs for a stated image-generation problem
Hooks
Event
Trigger
Action
PreToolUse
enqueue_workflow
VRAM watchdog — checks GPU memory via /system_stats and warns if < 1GB free before execution
PreToolUse
restart_comfyui (actions stop/restart)
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
Script
Description
monitor-progress.mjs
Progress monitor — connects to ComfyUI's WebSocket for real-time step progress (e.g., step 5/14 (36%)). Run as a background Bash task after enqueuing workflows. Reports completion with output filenames, errors with node details. Replaces polling queue (action:"status") in a loop.
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 or agent (a RunPod pod, a cloud box) you
can still run the agent on your machine and drive that remote ComfyUI. There is no
agent login on the box and nothing to install or configure remotely:
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
opens a 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 because of mixed-content and Private Network
Access rules. A local ComfyUI uses the plain ws://127.0.0.1:9199 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, with connect still running on your machine, open the remote ComfyUI in
your browser and click Connect in the Agent panel. The panel is a pure-frontend
extension. It links to the bridge your connect process is already serving, rather
than asking the ComfyUI host to spawn an orchestrator it cannot run.
Multi-provider, full parity. The orchestrator depends on a provider-neutral
AgentBackend port (dependency injection), with two adapters:
ClaudeBackend wraps the Claude Agent SDK
(@anthropic-ai/claude-agent-sdk), a persistent streaming session over the
claude.ai subscription (OAuth, no key).
CodexBackend wraps 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 tells the panel which features each backend supports (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 and 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:
Tool
Description
list_packs (action: "skill_list" / "skill_read")
Discover and read bundled model-family + workflow skills — the knowledge Claude loads natively, exposed to any MCP client (e.g. the Codex backend)
list_packs (action: "list" / "read_workflow")
List one-command installer packs (custom nodes + weights + ready workflow; all local-GPU / free) and read a pack's graph
list_packs (action: "list_templates")
List the connected ComfyUI's custom-node-contributed workflow templates
list_packs (action: "check_runtime")
Classify a workflow as local (your GPU, free) or api / mixed / unknown (hosted API nodes = paid credits) so the agent asks before spending paid API credits
Work out which custom node packs a workflow needs, and install the missing ones through ComfyUI-Manager
panel_load_workflow
(panel tool) Load a full workflow onto the live canvas in one shot — by bundled pack name (read server-side, never shuttled through chat) or by graph JSON
panel_strip_workflow / panel_slice_workflow
(panel tools) De-virtualize a tangled graph (Get/Set buses, Reroutes, subgraphs, bypass → real connections) or carve one rgthree-toggled pipeline out of a monolith — by pack, server-side path, or inline graph; for understanding/rebuilding expert workflows without hand-tracing
MCP Tools
38 tools across workflow execution, generation, iteration, composition, models, and more:
Image Generation (high-level)
Tool
Description
generate_imageaction: "image"
Generate from a text prompt — builds a txt2img workflow, fills unspecified params from your defaults, auto-selects a checkpoint
generate_imageaction: "controlnet"
Generate conditioned by a ControlNet image (pose/depth/canny/normal) + prompt
generate_imageaction: "ip_adapter"
Generate guided by a reference image's style/subject via IP-Adapter (needs ComfyUI_IPAdapter_plus)
generate_imageaction: "video" / "3d"
Generate a short video clip (LTX-2.3, local GPU) or a 3D model (hosted partner API nodes) from the same one-line entry point
generate_imageaction: "upscale"
Post-process an uploaded or staged image with ESRGAN super-resolution
generate_image (action:"remove_background")
Post-process an uploaded or staged image into a transparent BiRefNet cutout
Audio Generation (high-level)
Tool
Description
generate_imageaction: "audio"
Generate audio from a text prompt — supports ACE Step 1.5 (music with lyrics/structure) and Stable Audio 3 (music, instruments, SFX); auto-selects local models
Assets & Iteration
Tool
Description
get_image (action:"view")
Return a generated asset's bytes as an inline image so the agent can see the result
get_image (action:"analyze_color")
Palette / contrast / color statistics for a generated image (dominant colors, average + luminance stats, contrast checks) so the agent can reason about color without a vision round-trip
generate_image (action:"regenerate")
Re-run the workflow that produced an asset_id, with optional parameter overrides
get_image (action:"list_assets")
Browse recently generated assets (newest-first) by asset_id
get_image (action:"asset_metadata")
Full provenance for an asset, including the originating workflow
Defaults
Tool
Description
get_defaultsaction:"get"
Show merged generation defaults with per-source attribution
get_defaultsaction:"set"
Update runtime defaults; persist: true writes the config file
get_defaultsaction:"get_ui" / action:"set_ui"
Read/write ComfyUI's OWN frontend UI settings (the Comfy.* ids) — a separate store from the generation defaults above
Workflow Execution
Tool
Description
enqueue_workflowaction: "enqueue"
Submit a workflow (API format JSON) — returns prompt_id immediately, non-blocking
Re-run a past generation, or read/run a shared workflow from a URL, or inspect a bundled template's overridable slots
enqueue_workflow (action:"run_template")
One-shot: resolve a bundled pack's expert graph, apply <nodeId>.<widget> overrides, and enqueue it
queue
One action-parameterized tool for the execution queue: list (running + pending), status (one job by prompt ID), get_workflow (a pending job's full payload), move/edit (requeue a pending job front/back, patched or replaced, with a new prompt ID), cancel (interrupt the running job — escalates interrupt → verify → /free, reports WEDGED if it won't die; clear_pending: true also drops all pending), cancel_queued, clear
get_system_stats
Get system info — GPU, VRAM, Python version, OS
Workflow Visualization
Tool
Description
visualize_workflow
One action-parameterized tool for rendering and converting a workflow you pass in: render (Mermaid flowchart, nodes grouped by category), render_hierarchical (the same graph sectioned — overview, one section in detail, a listing, or an AI-oriented summary), mermaid (a Mermaid diagram back to executable workflow JSON), to_dsl/from_dsl (the compact, losslessly round-tripping authoring DSL)
Workflow Composition
Tool
Description
create_workflow
One action-parameterized tool for authoring: create (from templates: txt2img, img2img, upscale, inpaint, controlnet, ip_adapter, ace_step_15, stable_audio_3), modify (operations: set_input, add_node, remove_node, connect, insert_between), validate (dry-run — missing nodes, broken connections, invalid output indices, missing model files), node_info (query available node types from ComfyUI's /object_info endpoint)
Workflow Library
Tool
Description
get_workflow
One action-parameterized tool for READING a saved workflow file: list (the user library, subfolders included), get (one workflow's JSON by filename), analyze (a structured summary instead of raw JSON), query (filter/traverse/aggregate a big graph without dumping it), strip (de-virtualize any workflow from an absolute path, library filename, or inline graph — resolve GetNode/SetNode buses, Reroutes, subgraph defs, and bypassed nodes into real connections and return the flat graph; reads ANY path server-side, so it loads ad-hoc/expert workflows the cached library can't), slice (un-chunk a toggle-template monolith — one rgthree Fast-Groups-Bypass-toggled pipeline out into a standalone activated graph; pair with strip to then flatten the buses), from_image (the workflow ComfyUI embedded in a PNG), prompt_director (Prompt Director's sanitized runtime state)
save_workflow
One action-parameterized tool for WRITING to the library: save (store a workflow — overwrites a same-filename file), lock (record a provenance lock: SHA-256 per model, git commit per node pack), verify_lock (report drift against that lock)
Image Management
Tool
Description
upload_image
Copy a local image into ComfyUI's input/ directory for img2img, inpaint, or ControlNet
get_image (action:"list_outputs")
Browse recently generated images and videos from the output directory, sorted newest-first — recurses into subfolders (e.g. SaveVideo's output/video/…) and returns each result's subfolder
Model Management
Tool
Description
download_model
Find and fetch model weights, and track the transfers. action: download (from a URL, into the correct ComfyUI subdirectory), status, cancel, search (HuggingFace), search_civitai, search_creators, download_civitai, resolve_missing
list_local_models
What is installed, and where ComfyUI looks. action: list (installed models by type: checkpoints, loras, vae, upscale_models, controlnet, embeddings, clip, unet, diffusion_models, text_encoders), remove (deletes a model file), embeddings, list_paths, add_path, remove_path (the last three view/edit the extra search-path YAML)
Search the ComfyUI Registry for node packs by keyword (action: "search"), or get one pack's full details (action: "details")
list_packs (action: "generate_skill")
Generate a Claude skill .md file from a Registry ID or GitHub URL
comfy_cli
Search actual loaded node classes through official comfy nodes search (action:"search_nodes")
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 keep using Manager HTTP.
Tool
Description
comfy_cli
One action-parameterized tool for the whole official CLI: status, server_start/server_stop/server_restart, jobs_list/jobs_status/jobs_wait/jobs_watch/jobs_cancel, search_nodes, workflow_validate/workflow_run, transfer_upload/transfer_download, models_* (list/search/show/download/remove), skills_* (list/show/validate/install/status/uninstall)
Diagnostics
Tool
Description
get_system_stats (action:"logs")
Get ComfyUI server logs with optional keyword filter (e.g., error, warning, a node name)
kitchen
See what comfy-kitchen can do on this GPU (status), find where a graph leaves it on the table (assess), and apply the faster path (apply) — a failed probe is unknown, never a no
get_historyaction: "list"
Get execution history with full error details, Python tracebacks, timing, and cached node info
get_historyaction: "diagnose"
Explain a FAILED run in one call — the failed node and traceback PLUS the missing models (file + widget) and missing node types
Process Control
Tool
Description
restart_comfyuiaction:"restart"
Stop and restart ComfyUI, preserving all launch arguments
restart_comfyuiaction:"stop"
Stop the running ComfyUI process (saves PID and launch args for restart; on Windows, action:"start" cannot bring it back)
restart_comfyuiaction:"start"
Start ComfyUI using info saved from a previous stop (macOS/Linux; refused on Windows)
restart_comfyuiaction:"status"
Read-only: what start/stop/restart would do now, and whether a stop could be undone by this tool. Call it before stop
Generation Tracker
Tool
Description
get_historyaction: "suggest"
Suggest proven sampler/scheduler/steps/CFG settings from local generation history — query by model family, LoRA hash, or text search
get_historyaction: "stats"
Show local generation tracking statistics — total runs, unique combos, breakdown by model family
Every enqueue_workflow call logs settings to a local SQLite database (generations.db). Repeated settings combos get a reuse_count bump instead of a duplicate row, so the count works as a popularity signal. The tracker identifies models and LoRAs by content hash (AutoV2 / SHA256), not filename, so renamed files still group together.
# View local stats from the CLI
npm run generations:stats
Examples
Generate an image
> /comfy:gen a cyberpunk city at night with neon lights
Claude will:
Check installed checkpoints (download one if needed)
Build a txt2img workflow with your prompt
Execute it on ComfyUI
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
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.
> /comfy:recipe hires-fix a dramatic fantasy landscape with castles
Runs two passes: txt2img at 512x768, then an img2img upscale to 1024x1536 that adds detail.
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 their embedded metadata: checkpoint, prompt, seed, steps, CFG, and 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 the workflow.
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 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. Use the API Keys card (▾ menu next to "connected"). Keys are stored in ~/.comfyui-mcp/panel-secrets.json and take effect without a restart.
MCP-only setups (Claude Desktop, Claude Code, etc.). Use 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, the server also loads ~/.comfyui-mcp/.env 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:
Mode
Trigger
Local FS / process tools?
Local
default
yes
Remote
--comfyui-url / COMFYUI_URL points at a non-loopback host, or --force-remote is set
no — server skips COMFYUI_PATH auto-detection so stale local installs can't silently absorb uploads
no — HTTP primitives route via cloud.comfy.org over X-API-Key; WebSocket and local-only tools throw CLOUD_UNSUPPORTED
Some setups (e.g. dstack driving ComfyUI on RunPod) port-forward
a remote ComfyUI back to localhost:8188, so the loopback check above reports a
local install that isn't one. Pass --force-remote (or set
COMFYUI_MCP_FORCE_REMOTE=1) alongside --comfyui-url/COMFYUI_URL to force
remote mode regardless of hostname:
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_MCP_FORCE_REMOTE
Set to 1/true (or pass --force-remote) to force remote mode even when COMFYUI_URL/--comfyui-url resolves to a loopback host — for port-forwarded remote installs (e.g. dstack/RunPod) that are reachable at localhost. No effect without a COMFYUI_URL/--comfyui-url.
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 the ComfyUI data/base directory used for models, input/output and user state. In a conventional install this is also the checkout. Auto-detection suppressed in remote/cloud modes.
COMFYUI_CODE_PATH
COMFYUI_PATH
Optional path to the ComfyUI checkout (main.py, .venv, core git) when code and data live under different roots. Pip, venv, and core updates use this checkout (core updates prefer the checkout observed from the connected local server and use this as their fallback). Pack reads/writes — custom_nodes, comfy-cli --workspace, apply_manifest clone/checkout, workflow-lock pack commits — stay on the live --base-directory / COMFYUI_PATH data root (#1770).
COMFY_CLI_PATH
(auto-detect)
Path to the official comfy executable (comfy-cli >=1.11.1). Resolution also checks PATH and the selected workspace's .venv/venv.
COMFYUI_PYTHON
python
Python interpreter used by legacy git-clone dependency fallbacks. Point it at your ComfyUI venv's Python when needed.
COMFYUI_MCP_BRIDGE_HOST
127.0.0.1
Panel-bridge bind host. Set 0.0.0.0 (or a LAN IP) to run the orchestrator on a 24/7 server and connect panels from other machines — requires a token (below); the orchestrator prints a ready-to-paste ws://…/?token=… Bridge URL.
COMFYUI_MCP_BRIDGE_TOKEN
(generated when needed)
Shared secret gating every bridge connection (checked constant-time on the WS upgrade). Mandatory for a non-loopback COMFYUI_MCP_BRIDGE_HOST; pin it so the Bridge URL survives restarts. Never logged beyond the startup banner.
COMFYUI_MCP_DATA_DIR
~/.comfyui-mcp
Base dir for per-instance data (the generations.db behind get_historyaction: "suggest") when there's no local COMFYUI_PATH (remote/cloud/undetected). Scoped per target under instances/<host_port>/.
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
COMFYUI_DOWNLOAD_PROXY
Optional HTTP/HTTPS proxy for model-download traffic only; standard proxy environment variables and static Windows WinINet settings are also honored
GITHUB_TOKEN
GitHub token for skill generation (avoids rate limits)
REGISTRY_ACCESS_TOKEN
Comfy Registry API key for node_pack (action: "publish") (env-only, never logged)
Cap the download cache in GB; 0 disables LRU eviction
COMFYUI_STARTUP_CHECK_INTERVAL_S / …_MAX_TRIES
1 / 60
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 queue (action:"cancel") 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, which is what Claude Code, Claude Desktop, and the MCP Inspector expect, so no flags are needed. For MCP gateways, remote/hosted setups, or fetch-based clients, opt into streamable-HTTP:
Force remote mode for a loopback --comfyui-url (e.g. dstack/RunPod port-forwards to localhost)
Other agents & local LLMs (Hermes, OpenClaw, Copilot CLI, Ollama)
comfyui-mcp supports non-Claude harnesses. One command
writes the server entry into the harness's own config (it merges into an existing
file rather than overwriting it):
Model requirements. Tool calling is a hard requirement; a model without tool calling
doesn't work. Thinking and vision are recommended. Without
thinking, multi-step tool chains degrade; without vision the agent can
generate but can't see its own outputs.
Compact tool mode.--compact /
COMFYUI_MCP_TOOL_MODE=compact registers 3 meta-tools (list_tools →
describe_tool → call_tool) instead of the direct tool set, pulling schemas
into context one tool at a time. That is the right trade for small local models. The
direct tool set is the default and is what frontier-model harnesses want.
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) is Gemma 4, QLoRA-trained on 1,055
server-verified trajectories over the full comfyui-mcp tool set, and is the
panel's Ollama default. Stock gemma4:*/qwen3:4b are also validated end-to-end
(npm run test:local-llm); gemma3 has no native tool calling and is
unsupported. The full guide, covering hosted-model guidance (DeepSeek/MiMo/GLM class),
per-harness setup, and troubleshooting, is
Local LLMs & other agents.
Flag
Env
Default
Description
setup <agent>
Write the comfyui entry into hermes / openclaw / copilot config, then exit
--compact / --tool-mode compact
COMFYUI_MCP_TOOL_MODE=compact
full
Opt into the 3 meta-tools (list_tools / describe_tool / call_tool) instead of the direct tool set — recommended for small local models. --full is still accepted and is now a no-op
Remote ComfyUI
Point the server at a ComfyUI running anywhere; no local install is required:
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):
All communication with the MCP client (Claude Code) happens over stdio using the Model Context Protocol. Logs go to stderr so they never mix into the protocol stream.
scripts/
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 get_workflow's strip action)
workflow-slicer.ts # sliceWorkflow() — rgthree Fast-Groups-Bypass pipeline un-chunker (shared by the CLI + get_workflow's slice action)
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
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 (render/render_hierarchical/mermaid/to_dsl/from_dsl)
workflow-compose.ts # create_workflow (create/modify/validate/node_info)
workflow-validate.ts # the validate action's body
workflow-library.ts # get_workflow (8 read actions), save_workflow (save/lock/verify_lock)
image-management.ts # get_image (7 read actions), upload_image (5 write actions)
model-management.ts # download_model, list_local_models (the two consolidated model tools)
memory-management.ts # clear_vram
registry-search.ts # search_custom_nodes (search/details)
node-management.ts # install_custom_node (install/update/fix/uninstall/enable/disable/list/…)
node-pack.ts # node_pack (scaffold/verify/publish/read/write/patch/git/…)
generation-tracker.ts # the get_history suggest/stats jobs
diagnostics.ts # get_system_stats (action:"logs"), get_history
process-control.ts # restart_comfyui (restart/start/stop)
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
launch-server.mjs # MCP server launcher — global install if present, else npx with a
# cold-start handshake rescue so a first run cannot time out (#1447)
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 diagnose failures. Or call get_history (action: "diagnose") / get_system_stats (action:"logs") directly to see the full 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 warns you when less than 1GB is free before a workflow runs. 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 detects missing packs and suggests them.
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 (make sure 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.
Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no A
Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no API key), free local models via Ollama (fully offline),
上次检查时间：2026-11-15。 Local-first, agent-native control plane for ComfyUI — MCP server + autonomous sidebar agent that drives your live graph in natural language on ANY LLM: Claude/ChatGPT/Gemini on your subscription (no API key), free local models via Ollama (fully offline),