Skip to main content
Glama

mcp-comfy-ui-builder

Control ComfyUI from Claude or Cursor — 50+ MCP tools for node discovery, dynamic workflow building, real-time WebSocket execution, and model management. No JSON editing required.

CI npm Docker License: MIT

Tell your AI assistant what image to generate — it builds and runs the ComfyUI workflow for you.
Works with Claude Desktop, Cursor, and any MCP-compatible client.

Demo

Publishable to the MCP Registry via server.json and mcpName.

What is this

  • Knowledge base: Seed knowledge/base-nodes.json and node-compatibility.json from bundled data (62 seed nodes; 100–600+ after sync). No external services required for suggest/build.

  • Sync: Custom packs from ComfyUI-Manager; nodes from running ComfyUI via sync-nodes CLI or on MCP startup.

  • MCP server (50+ tools): Node discovery, dynamic workflow builder, 9 templates (txt2img, txt2img_flux, img2img, …), WebSocket real-time execution, batch/chain, model management, plugin system.

  • Real-time execution: Sub-second progress via WebSocket with automatic polling fallback; ~90% less network traffic for batch runs.

Related MCP server: ComfyUI MCP Server

Install

npm install mcp-comfy-ui-builder

Or from source: git clone https://github.com/MIt9/mcp-comfy-ui-builder.git && cd mcp-comfy-ui-builder && npm install

Quick start

  1. Build (postbuild fills knowledge from seed)

    npm run build
    npm run mcp
  2. Use knowledge in code

    import baseNodes from './knowledge/base-nodes.json' assert { type: 'json' };

Commands

Command

Description

npm run seed

Fill knowledge from seed. Use --force to overwrite.

npm run sync-manager

Update custom packs list from ComfyUI-Manager

npm run sync-nodes

Sync nodes from running ComfyUI to knowledge base (requires COMFYUI_HOST)

npm test

Run tests (vitest)

npm run mcp

Start MCP server (after npm run build)

Documentation

Single entry point — task-oriented navigation:

Requirements

  • Node.js 18+

MCP Server (Cursor / Claude)

Server provides 50+ tools across 9 categories:

Core Features

Node Discovery:

  • list_node_types, get_node_info, check_compatibility, suggest_nodes

  • discover_nodes_live, search_nodes, sync_nodes_to_knowledge

Dynamic Workflow Builder:

  • create_workflow, add_node, connect_nodes, validate_workflow

  • Build workflows programmatically without JSON manipulation

Templates & Macros:

  • list_templates, build_workflow — Pre-built templates (txt2img, img2img, inpainting, upscale, LoRA, ControlNet, batch)

  • create_template, apply_template — Parameterized templates

  • list_macros, insert_macro — Reusable sub-workflows

Real-time execution 📡

  • execute_workflow_sync — Execute with WebSocket progress streaming (sub-second updates)

  • execute_workflow_stream — Full event history collection (WebSocket-only)

  • get_execution_progress — Real-time progress with node-level granularity

  • execute_batch — Concurrent execution with 90% reduced network traffic

  • execute_chain — Sequential workflows with data passing

Resources & Model Management:

  • get_system_resources — GPU/VRAM/RAM + recommendations (max resolution, model size, batch size); call first before building workflows to avoid OOM

  • list_models, check_model_exists, get_workflow_models

  • Supports checkpoint, lora, vae, controlnet, upscale, embedding, clip

Outputs & Queue:

  • list_outputs, download_output, download_all_outputs

  • list_queue, interrupt_execution, clear_queue

Plugins:

  • list_plugins, reload_plugins — Data-only plugin system

Install (requires COMFYUI_PATH):

  • install_custom_node, install_model — Install nodes and models via ComfyUI-Manager

WebSocket features

  • <100ms latency for progress updates (vs 1.5s polling)

  • Node-level tracking: See exactly which node is executing with progress percentage

  • Automatic fallback: Gracefully falls back to polling if WebSocket unavailable

  • Shared connection: Single WebSocket for batch/chain execution (90% reduced traffic)

Set COMFYUI_HOST environment variable for execution/model/output tools:

export COMFYUI_HOST="http://localhost:8188"

See doc/MCP-SETUP.md for full tool list and doc/WEBSOCKET-GUIDE.md for real-time features.

Running MCP

From project root, first build the project, then start the server:

npm run build
npm run mcp

Or without npm: node dist/mcp-server.js. Server works via stdio (stdin/stdout). More details → doc/MCP-SETUP.md.

Connect MCP (Cursor / Claude)

What you need: Node.js 18+, one-time build (npm run build), absolute path to dist/mcp-server.js, restart after config change. If the server fails to start with «spawn node ENOENT», use the full path to node in command (run which node and put that path). See doc/MCP-SETUP.md → Troubleshooting.

Minimal config (knowledge and workflow tools only):

{
  "mcpServers": {
    "comfy-ui-builder": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/mcp-comfy-ui-builder/dist/mcp-server.js"]
    }
  }
}

Use full path in command (e.g. "/opt/homebrew/bin/node") if Cursor/IDE reports «spawn node ENOENT».

With ComfyUI execution (execute_workflow, get_execution_status, list_outputs, etc.): add "env": { "COMFYUI_HOST": "http://127.0.0.1:8188" } to the server block. See doc/MCP-SETUP.md for full checklist, optional env vars (COMFYUI_PATH, COMFYUI_KNOWLEDGE_DIR), and troubleshooting.

Publish on GitHub

  1. Create a new repository on GitHub: name mcp-comfy-ui-builder, visibility Public (or Private). Do not initialize with README, .gitignore, or license (project already has them).

  2. Add remote and push:

    git remote add origin https://github.com/MIt9/mcp-comfy-ui-builder.git
    git branch -M main
    git push -u origin main
  3. If you fork this repo, replace MIt9 with your GitHub username in the URLs above.

Cursor: Settings → MCP; Claude Desktop: config file ~/Library/Application Support/Claude/claude_desktop_config.json (macOS). Replace the path with your absolute path to dist/mcp-server.js, then restart the app. Full guide: doc/MCP-SETUP.md.

License

MIT

Available Tools

61 tools
add_nodeB

Add a node to a dynamic workflow. Returns the new node id (e.g. "1", "2").

Inputs: class_type (required), workflow_id (required), inputs.

apply_templateA

Apply parameter values to a workflow template. Returns workflow JSON ready to execute or save. Use create_template to build a template, then apply_template with values.

Inputs: values (required), template (required).

build_restyle_workflowA

Build a workflow that takes your image and outputs another image in a chosen style (cartoon, oil painting, anime, etc.). Returns workflow JSON plus a recipe (prompt and params) so you can run it or regenerate with the same settings. Image must be in ComfyUI input folder (upload first if needed). Style: keyword (cartoon, oil_painting, anime, watercolor, sketch, comic, pixel_art, pastel, cyberpunk) or any free text used as prompt.

Inputs: image (required), style (required), cfg, seed, +6 more.

build_workflowA

Build a ComfyUI workflow from a template and parameters. Returns workflow JSON ready to execute or save. For txt2img_flux, call get_system_resources first and use only when flux_ready is true (FLUX needs ~12GB+ VRAM).

Inputs: template (required), params.

check_compatibilityA

Check if output of one node can connect to input of another (using node-compatibility.json).

Inputs: to_node (required), from_node (required).

check_model_existsA

Check if a model exists on the ComfyUI server (in object_info model lists). Requires COMFYUI_HOST.

Inputs: name (required), type (required).

check_workflow_modelsA

Check which models required by a workflow exist on the ComfyUI server. Returns ready (boolean), missing, and found lists. Requires COMFYUI_HOST.

Inputs: workflow (required).

clear_queueA

Clear ComfyUI queue: remove all pending and stop/clear running. Requires COMFYUI_HOST.

Inputs: no named parameters.

connect_nodesC

Connect an output of one node to an input of another in a dynamic workflow.

Inputs: to_node (required), from_node (required), input_name (required), output_idx (required), +1 more.

create_templateA

Create a parameterized workflow template from a workflow and parameter definitions. Returns template JSON for use with apply_template or validate_template_params. Parameters bind to node inputs via nodeBindings (nodeId, inputName).

Inputs: params (required), workflow (required), name, category, +1 more.

create_workflowA

Create a new empty workflow context. Returns workflow_id to use with add_node, connect_nodes, get_workflow_json, validate_workflow, finalize_workflow, execute_workflow.

Inputs: no named parameters.

delete_queue_itemsA

Remove specific items from ComfyUI queue by prompt_id. Use list_queue to get prompt_ids. Requires COMFYUI_HOST.

Inputs: prompt_ids (required).

discover_nodes_liveA

Get all node definitions from the running ComfyUI instance (GET /object_info). Returns class names and categories. Requires ComfyUI to be running at COMFYUI_HOST.

Inputs: no named parameters.

download_all_outputsB

Download all output files for a prompt into a directory. Returns list of saved paths. Requires COMFYUI_HOST.

Inputs: dest_dir (required), prompt_id (required), prefix_node_id.

download_by_filenameA

Download an output file by filename (no prompt_id needed). Uses GET /view. Use when you have filename from get_history or get_last_output. If return_base64 is true, file is not written to disk; returns base64 data. When size > 800 KB, automatically converts to WebP to stay under 1MB base64 limits. Use output_format to convert to png, jpeg, or webp. Requires COMFYUI_HOST.

Inputs: filename (required), dest_path (required), type, subfolder, +4 more.

download_outputA

Download a single output file to a local path. Use list_outputs to get file info. Use output_format to convert to png, jpeg, or webp. Requires COMFYUI_HOST.

Inputs: node_id (required), filename (required), dest_path (required), prompt_id (required), +3 more.

execute_batchB

Execute multiple workflows in batch. Submits each workflow and waits for completion (polling). Optional concurrency and stop_on_error. Requires COMFYUI_HOST.

Inputs: workflows (required), timeout_ms, concurrency, stop_on_error.

execute_chainA

Execute a chain of workflows in sequence. Each step runs after the previous completes. Use inputFrom and outputTo to pass the output image from one step to the next (e.g. txt2img → upscale → img2img). Steps can use workflow JSON or saved workflow name. Prefer saved workflow name (string) for large workflows to avoid ENAMETOOLONG in some clients. Requires COMFYUI_HOST.

Inputs: steps (required), timeout_ms, stop_on_error.

execute_workflowA

Submit a ComfyUI workflow to run. Returns prompt_id. Use get_execution_status(prompt_id) to check result. Requires COMFYUI_HOST and ComfyUI running.

Inputs: workflow (required).

execute_workflow_streamB

Execute workflow with streaming real-time progress updates. Requires WebSocket support. Returns result and progress event history. Use for monitoring execution progress. Requires COMFYUI_HOST and WebSocket connection.

Inputs: workflow (required), timeout_ms.

execute_workflow_syncA

Submit a ComfyUI workflow and wait until execution completes with real-time progress (WebSocket if available, polling fallback). Returns prompt_id, status (completed/failed/timeout), and outputs. When status is error, still check outputs — if present, use download_output or get_last_output to retrieve files. When timeout_ms is omitted, uses recommended_timeout_ms from get_system_resources (higher on MPS/Apple). Requires COMFYUI_HOST.

Inputs: workflow (required), timeout_ms, stream_progress.

finalize_workflowC

Get the workflow JSON for a dynamic workflow (same as get_workflow_json). Use with execute_workflow or save_workflow.

Inputs: workflow_id (required).

get_error_detailsA

Get full error details for a prompt (node_id, exception_type, exception_message, full traceback). Use when execute_workflow_sync failed or get_execution_status shows errors. Returns structured errors from ComfyUI history status.messages. Requires COMFYUI_HOST.

Inputs: prompt_id (required).

get_execution_progressA

Get real-time execution progress for a prompt (WebSocket if available, polling fallback). Returns status, current_node, progress%, queue_position, and outputs. Requires COMFYUI_HOST.

Inputs: prompt_id (required).

get_execution_statusA

Get execution status and outputs for a prompt. Returns status, image filenames, and view URLs. Requires COMFYUI_HOST.

Inputs: prompt_id (required).

get_generation_recommendationsA

Get recommendations for image generation: system resources (max resolution, model size, batch) and, if the user prompt suggests text/letters in the image, advice on models and settings. Many base models (SD 1.5, SD XL) render text poorly; FLUX, SD 3, or checkpoints trained for text work better. Call when planning a txt2img or img2img workflow; pass the user's image description as prompt to get text-in-image advice when relevant. Requires COMFYUI_HOST for resource stats.

Inputs: prompt.

get_historyA

Get ComfyUI execution history (GET /history) without prompt_id. Returns last N prompts with prompt_id, status, outputs (filenames), elapsed. Use when execute_workflow_sync did not return prompt_id (e.g. WebSocket timeout) to find the latest run and its outputs. Requires COMFYUI_HOST.

Inputs: limit.

get_last_outputA

Get info for the most recent prompt that has image output (skips failed prompts). Use when prompt_id was lost (e.g. execute_workflow_sync timed out). Returns prompt_id, filename, subfolder, view_url. Then use download_by_filename to save the file. Requires COMFYUI_HOST.

Inputs: no named parameters.

get_model_infoB

Get info for a model by name and type. Returns name, type, path; null if not found. Requires COMFYUI_HOST.

Inputs: name (required), type (required).

get_node_infoB

Get full node information for a ComfyUI node by its class name. Uses live ComfyUI when COMFYUI_HOST is set, otherwise knowledge base.

Inputs: node_name (required).

get_node_inputsA

Get detailed input definitions for a node (required and optional). Uses live ComfyUI if available, otherwise knowledge base.

Inputs: node_name (required).

get_node_outputsB

Get output types and names for a node. Uses live ComfyUI if available, otherwise knowledge base.

Inputs: node_name (required).

get_system_resourcesA

Get ComfyUI station resources (GPU/VRAM/RAM) and recommendations for model size, resolution, and batch size. Returns flux_ready (desktop FLUX needs ~12GB+ VRAM) and platform_hints (e.g. Apple Silicon: M-Flux as quantized/MLX variant — different model or FLUX via custom nodes). Call this first before building or executing workflows to avoid OOM. Requires COMFYUI_HOST.

Inputs: no named parameters.

get_workflow_jsonB

Get the current workflow JSON for a dynamic workflow (for execute_workflow or save_workflow).

Inputs: workflow_id (required).

get_workflow_modelsA

Extract required models from a workflow (loader nodes: CheckpointLoaderSimple, LoraLoader, VAELoader, ControlNetLoader, UpscaleModelLoader, etc.). Returns list of { name, type, nodeId, nodeClass, inputName }. No ComfyUI connection needed.

Inputs: workflow (required).

insert_macroA

Insert a macro (sub-workflow) into a dynamic workflow. Connects macro input ports to existing nodes. Returns nodeIdMap and outputPorts so you can connect macro outputs. Use workflow_id from create_workflow.

Inputs: macro_id (required), workflow_id (required), input_connections (required).

install_custom_nodeA

Install one or more custom nodes via ComfyUI-Manager cm-cli (e.g. ComfyUI-Blip, WAS-Node-Suite). Requires COMFYUI_PATH and ComfyUI-Manager installed in custom_nodes. ComfyUI-Manager cm-cli requires Python package "rich" (pip install rich in your ComfyUI Python environment). Restart ComfyUI after install to load new nodes.

Inputs: node_names (required), mode, channel.

install_modelA

Download and install a model (checkpoint, LoRA, VAE, etc.) by URL. Requires COMFYUI_PATH. Uses comfy-cli if available (pip install comfy-cli), otherwise fetches the file directly. model_type: checkpoint, lora, vae, controlnet, clip, embeddings, hypernetwork, upscale_models, clip_vision, unet, diffusers.

Inputs: url (required), model_type.

interrupt_executionA

Stop the currently running workflow on ComfyUI. Optionally pass prompt_id to interrupt only that prompt. If cleanup_after_ms is set (and prompt_id given), after interrupt the tool will poll the queue and remove the prompt from queue if it is still there (frees GPU for next job). Requires COMFYUI_HOST.

Inputs: prompt_id, cleanup_after_ms.

list_macrosA

List available workflow macros (built-in sub-workflows). Returns id, name, description, inputs, outputs.

Inputs: no named parameters.

list_modelsA

List models available on the ComfyUI server (from object_info). Optionally filter by type: checkpoint, lora, vae, controlnet, upscale, embedding, clip. Requires COMFYUI_HOST.

Inputs: type.

list_node_categoriesA

List all node categories from live ComfyUI and knowledge base (merged, unique).

Inputs: no named parameters.

list_node_typesB

List ComfyUI node types from the knowledge base. Optionally filter by category or priority.

Inputs: category, priority.

list_outputsA

List all output files (images, gifs) for a completed prompt. Returns prompt_id, node_id, type, filename, url. Requires COMFYUI_HOST.

Inputs: prompt_id (required).

list_pluginsA

List loaded plugins (from plugins/*/plugin.json) and counts of macros/templates contributed by each.

Inputs: no named parameters.

list_queueA

List current ComfyUI queue (running and pending prompts). Requires COMFYUI_HOST.

Inputs: no named parameters.

list_saved_workflowsA

List saved workflows (names and paths) from workflows/ directory.

Inputs: no named parameters.

list_templatesA

List available workflow template ids (e.g. txt2img). No ComfyUI connection needed.

Inputs: no named parameters.

load_workflowA

Load a saved workflow by name (from workflows/.json) or by path. Returns workflow JSON for use with execute_workflow or save_workflow.

Inputs: name_or_path (required).

prepare_image_for_workflowA

Fetch the first output image from a completed prompt and upload it to ComfyUI input folder. Returns the filename to use in LoadImage for a follow-up workflow (e.g. image caption / verification). Use after get_execution_status confirms the prompt finished with image output. Requires COMFYUI_HOST.

Inputs: prompt_id (required).

reload_comfyuiA

Restart ComfyUI so that newly installed custom nodes are loaded, then optionally sync them to the knowledge base. Requires COMFYUI_PATH (ComfyUI installation directory) and uses COMFYUI_HOST for the port. Kills the process on the ComfyUI port and starts main.py from COMFYUI_PATH. After restart, call sync_nodes_to_knowledge to pick up custom nodes (or set sync_after_restart to true).

Inputs: wait_for_ready, wait_timeout_ms, sync_after_restart.

reload_pluginsB

Reload plugins from plugins/*/plugin.json and refresh macro registry.

Inputs: no named parameters.

remove_nodeA

Remove a node from a dynamic workflow. Does not fix references (validation will report dangling refs).

Inputs: node_id (required), workflow_id (required).

save_workflowA

Save a workflow JSON to file (workflows/.json). Returns path. Use after build_workflow to persist for later load_workflow or execute_workflow.

Inputs: name (required), workflow (required).

search_nodesA

Search nodes by query string and optional filters (category, input_type, output_type). Searches both live ComfyUI and knowledge base; live overrides KB for same class.

Inputs: query, category, input_type, output_type.

set_node_inputB

Set a literal input on a node in a dynamic workflow (overwrites existing value or link).

Inputs: value (required), node_id (required), input_name (required), workflow_id (required).

suggest_nodesB

Suggest ComfyUI nodes for a task (search by description/use_cases) or by output type they produce.

Inputs: input_type, task_description.

suggest_template_for_checkpointA

Suggest workflow template (txt2img_flux or txt2img) from checkpoint filename. FLUX checkpoints (e.g. flux1-dev-fp8.safetensors) use txt2img_flux; SD XL / SD 1.5 use txt2img. Call before build_workflow when the user did not specify a template.

Inputs: ckpt_name (required).

sync_nodes_to_knowledgeA

Sync node definitions from running ComfyUI to the knowledge base. Adds only nodes that are not already in base-nodes.json. Creates knowledge/ if missing (or set COMFYUI_KNOWLEDGE_DIR to point to the knowledge directory). Requires ComfyUI to be running.

Inputs: no named parameters.

validate_template_paramsB

Validate that parameter values satisfy a workflow template (required params, types).

Inputs: values (required), template (required).

validate_workflowB

Validate a dynamic workflow: checks that all node references exist and output indices are valid.

Inputs: workflow_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 61 tools

    Disambiguation2/5

    Several tools have heavily overlapping boundaries: finalize_workflow is explicitly identical to get_workflow_json; execute_workflow_sync vs execute_workflow_stream vs get_execution_status/progress/history/last_output are multiple paths to similar monitoring; download_output/download_by_filename/download_all_outputs overlap; and node discovery is spread across list_node_types, search_nodes, discover_nodes_live, suggest_nodes, and get_node_info. Descriptions help, but an agent must still reason carefully to pick the right tool for many common tasks.

    Naming Consistency4/5

    Names are consistently snake_case and mostly follow verb_noun patterns such as list_models, get_model_info, execute_workflow, and download_output. Minor deviations exist (interrupt_execution, clear_queue, apply_template) and a few near-duplicate names like finalize_workflow vs get_workflow_json weaken predictability, but overall the convention is readable.

    Tool Count1/5

    With 61 tools, the surface is far too large for a coherent single server. Many capabilities are split into multiple similar tools rather than consolidated, making the set difficult to navigate and increasing selection errors.

    Completeness4/5

    Coverage is broad: node discovery, workflow construction, templates, macros, execution, queue control, output download, model management, plugin reloading, and saved-workflow persistence are all represented. Minor gaps remain, such as deleting saved workflows, but core ComfyUI lifecycle workflows are well covered.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers