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

1. Optionally list checkpoints with the models tool (checkpoints folder).
2. If no checkpoint is installed, use comfyui_get_manager_status, then comfyui_search_model_catalog to find a catalog entry, then comfyui_install_model with those exact fields (Desktop includes Manager; CLI needs --enable-manager).
3. Fetch node schemas when unsure of input names (KSampler, etc.).
4. Queue the graph — response includes prompt_id.
5. Poll history with that prompt_id until outputs appear.
6. Fetch images with filename/subfolder/type from history metadata.
7. Upload datasets or download trained weights with comfyui_put_file / comfyui_get_file (paths under input/, output/, or models/ only).

LoRA training (kohya through ComfyUI)

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

Training setup flow:

1. comfyui_list_custom_nodes with node_classes to confirm training nodes exist.
2. If missing: comfyui_search_custom_node_catalog, then comfyui_install_custom_node.
3. comfyui_install_node_requirements for the pack when pip deps are missing.
4. comfyui_install_model / comfyui_put_file for checkpoint and dataset files.
5. After a failed or OOM run: comfyui_interrupt if needed, then comfyui_free_memory (set wait_until_vram_free_mb to confirm VRAM dropped). If weights stay resident, comfyui_reboot_comfyui through Manager.
6. Queue the FluxTrainer workflow, poll history, comfyui_get_file for the .safetensors output.

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.

Agent operations (queue, memory, validation)

Recovery after a failed or OOM run:

1. comfyui_interrupt — stop the in-progress job.
2. comfyui_clear_queue — drop pending jobs that would re-run on stale VRAM.
3. comfyui_free_memory — unload models and clear execution cache on the next idle tick. Optional wait_until_vram_free_mb polls /system_stats until free VRAM rises.
4. comfyui_reboot_comfyui — hard restart through ComfyUI-Manager when /free is not enough.

Authoring and execution:

• comfyui_validate_workflow — live check of wires, paths, and registered node classes (complements offline comfyui_index_validate_draft).
• comfyui_get_workflow_template — starter API prompts for common graphs (wan_t2v_native_1_3b for built-in WAN).
• comfyui_list_local_files — confirm input datasets and models/ checkpoints on disk.
• comfyui_wait_for_history — wait until a queued job finishes. Default poll_mode=auto tries WebSocket progress (value/max for ETA) then falls back to HTTP poll (GET /history/{prompt_id} + GET /queue) on keepalive-only streams or WebSocket errors — never fails the turn on stream parse misses. For LoRA training over ~15 minutes use poll_mode=http with timeout_seconds=3600, or loop comfyui_get_queue + comfyui_get_history manually. Returns output_files paths for comfyui_get_file and last_progress when seen.
• comfyui_install_missing_nodes_for_workflow — Manager install for unregistered node classes.
• comfyui_get_import_fail_info — diagnose packs that installed but failed to import.

Model install (ComfyUI-Manager)

• comfyui_search_model_catalog reads the Manager install catalog (/v2/externalmodel/getlist) and returns fields for comfyui_install_model.
• comfyui_install_model uses the same Manager download queue as the ComfyUI UI — not arbitrary URLs. Returns already_installed when the file is already visible under comfyui_list_models (idempotent).
• Requires ComfyUI-Manager on the instance (comfyui_get_manager_status first). active_queue_items shows stuck installs; comfyui_reset_manager_queue clears a zombie Manager queue without deleting files.
• Large checkpoints may still download after the tool returns in_progress; poll with comfyui_get_model_install_status or comfyui_list_models.

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: Image and video fetches need exact paths from history — not guessed. comfyui_wait_for_history returns output_files with comfyui_get_file paths. comfyui_list_local_files zone=output is unreliable for SaveVideo nested folders on Desktop.
• Long training runs: TrainLoraNode and similar jobs may run 15–60+ minutes with no intermediate history. Use comfyui_wait_for_history with poll_mode=http and a long timeout_seconds, or poll comfyui_get_queue + comfyui_get_history in a loop until the LoRA appears under models/loras/.
• node_errors: Invalid graphs return structured node_errors from the queue endpoint; fix inputs and retry.
• Interrupt vs queue: Interrupt stops the current job; it does not clear pending queue items.
• Interrupt vs free memory: comfyui_free_memory unloads models on the next idle tick; set wait_until_vram_free_mb to confirm VRAM dropped, or comfyui_reboot_comfyui when Flux weights stay loaded.
• Windows paths: comfyui_validate_workflow and comfyui_run_workflow normalize path strings to the host separator before queueing.
• Object info size: Full node catalog is huge; request one node_class at a time when building graphs.