ComfyUI MCP Server

ComfyUI (local)

ComfyUI is a node-graph engine for diffusion and generative media. This bundle reaches the HTTP API on the user's machine through MCPBundles Desktop — not a hosted ComfyUI cloud.

Runtime requirements

• ComfyUI Desktop or a ComfyUI server must be running locally with the HTTP API enabled.
• ComfyUI Desktop defaults to 127.0.0.1:8000; CLI/portable installs often use 8188.
• MCPBundles Desktop must be running on the same machine so the backend can forward HTTP to localhost.

Workflow shape

ComfyUI executes API prompt JSON: a map of string node ids to [node_class, {inputs}]. Example node classes: CheckpointLoaderSimple, CLIPTextEncode, KSampler, VAEDecode, SaveImage.

Typical generation flow:

1. Optionally list checkpoints under the checkpoints models folder.
2. Validate the graph before queueing — validation reports missing_models when weights are absent; it never auto-downloads.
3. Manager-listed weights: search the ComfyUI-Manager catalog, then queue install with the exact catalog fields (name, type, base, save_path, filename, url).
4. Weights not in Manager (ACE-Step, Stable Audio, template-only HuggingFace assets): download each missing file explicitly into the correct models/{folder}/ path.
5. Probe one node class at a time when building graphs — the full object-info catalog is huge.
6. Queue the graph; the response includes prompt_id.
7. Wait with comfyui_wait_for_history for that prompt_id until status=success and output_files is populated.
8. Pull each output using output_files[].fetch_tool and fetch_params — videos, gifs-bucket media, and audio use comfyui_get_output; models and safetensors use comfyui_get_file.
9. Never guess filenames from Save node filename_prefix alone — paths include ComfyUI suffixes (_00001, nested subfolders).
10. Upload datasets or small files under input/, output/, or models/ only (put is capped at 100 MB).

Output pull workflow (mandatory)

The root cause of “invisible” outputs is skipping history metadata and guessing paths. The correct chain:

• output_files is authoritative for MCP-queued runs. Each entry includes fetch_tool, fetch_params, and path.
• comfyui_list_local_files (zone=output) walks on-disk folders — useful for browsing datasets, not as a substitute for history after a fresh queue.
• file_path is accepted as an alias for path on comfyui_get_file.
• comfyui_get_file falls back to HTTP /view when desktop disk read fails; on miss it retries exact candidate paths when disk listing finds them.
• Caller-side persistence (saving bytes to a project folder) stays outside this provider. A future comfyui_sync_job may chain queue → wait → pull in one call.

LoRA training (kohya through ComfyUI)

Kohya sd-scripts runs inside ComfyUI via custom node packs (for example Kijai's ComfyUI-FluxTrainer with InitFluxLoRATraining, FluxTrainLoop, FluxTrainSave). Queue training like any other graph — there is no separate kohya server.

Training setup order:

1. Confirm training node classes are registered on the instance.
2. If missing: search the Manager custom-node catalog, install the pack, then install pip requirements for that pack.
3. Place checkpoint and dataset files via Manager install or file upload.
4. After a failed or OOM run: interrupt if needed, free GPU memory (optionally wait until free VRAM rises), reboot through Manager only when unload is not enough.
5. Queue the FluxTrainer workflow, poll history, pull the .safetensors output from disk.

ComfyUI's built-in TrainLoraNode is a different trainer — not kohya. Prefer FluxTrainer nodes for kohya-style training and memory options such as blocks_to_swap on constrained GPUs.

Queue, memory, and recovery

After a failed or OOM run:

1. Interrupt stops the in-progress job only — it does not clear pending queue items.
2. Clear the queue to drop pending jobs that would re-run on stale VRAM.
3. Free memory unloads models on the next idle tick; optional VRAM polling uses /system_stats.
4. Manager reboot is the hard reset when /free is not enough.

Long jobs (LoRA training, 15–60+ minutes): prefer HTTP polling with a long timeout, or loop queue + history until the LoRA appears under models/loras/.

Validation, templates, and Manager installs

• Live validation checks wires, paths, registered node classes, and missing weights on disk.
• Workflow templates ship starter API prompts for common graphs (for example built-in WAN).
• List local files to confirm datasets and checkpoints on disk before queueing.
• Output discovery on Desktop: comfyui_list_local_files with zone=output and subpath (for example video/smoke_test) walks on-disk output via MCPBundles Desktop — use before queueing to confirm datasets, not as a substitute for output_files after MCP-queued runs.
• Wait-for-history can use WebSocket progress when available, then fall back to HTTP poll without failing the turn on stream parse misses.
• Install missing custom nodes for unregistered classes in a workflow via Manager.
• Import-fail diagnostics explain packs that installed but failed to load.
• Node schema probes return registered: false when a class is not loaded.

Manager catalog and direct downloads

• Model catalog search reads /v2/externalmodel/getlist; installs use Manager's download queue (not arbitrary URLs). Idempotent when the file is already visible in the models list.
• Custom-node catalog may be empty on ComfyUI Desktop until the database channel is set correctly — read Manager channel config (selected channel, db_mode) when search returns zero; probe /v2/customnode/getlist with mode=remote via the generic local HTTP request escape hatch when needed.
• The install snapshot lists git custom node packs with enabled/disabled flags when the installed-pack route returns sparse rows on Desktop V4 builds.
• List all model folder types (not only checkpoints/loras) before searching niche weight paths such as ipadapter or diffusion_models.
• Manager install rejections often return HTTP 400; use allow_error_response on that escape hatch to read the raw body. Set expect_json=false for plain-text Manager policy routes.
• Git URL custom-node installs are blocked when Manager security policy is strict — lower security in Desktop settings or install from the Manager UI.
• Large checkpoints may still download after install returns in_progress; poll install status or list models.
• Direct HuggingFace/Civitai downloads into models/{save_dir}/ when validation reports missing_models and the weight is not catalog-listed. Use background download (default) for multi-GB files, then poll download status or list models — blocking downloads hold the MCP SSE stream open and fail after ~15–20 minutes even though the ComfyUI host may still be downloading on disk.

Gotchas

• Local GPU time: Runs on the user's hardware; large graphs can take minutes.
• No built-in auth: Default ComfyUI binds to localhost only. Do not expose the port to the public internet.
• History outputs: Always pull via output_files from comfyui_wait_for_history using each entry's fetch_tool. Videos/gifs/audio use comfyui_get_output; safetensors use comfyui_get_file.
• node_errors: Invalid graphs return structured errors from the queue endpoint; fix inputs and retry.
• Windows paths: Validation and queue normalize path separators to the host before running.
• Large local files: Multi‑MB .safetensors may return a download link (spillover) instead of inline base64.