MCP Comfy Ui Builder

🚀 mcp-comfy-ui-builder

ComfyUI Node Discovery — A seed knowledge base and MCP tools for Cursor/Claude. It can be published to the MCP Registry via server.json and mcpName.

This project offers a knowledge base seeded from bundled data, sync capabilities for custom packs and running ComfyUI nodes, an MCP server with over 50 tools, and real - time execution features with reduced network traffic.

🚀 Quick Start

Build

npm run build
npm run mcp

Use knowledge in code

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

✨ Features

• Knowledge base: Seed knowledge/base-nodes.json and node-compatibility.json from bundled data (62 seed nodes; 100 - 600+ after sync). No external services are 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.

📦 Installation

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

💻 Usage Examples

Basic Usage

# Build the project
npm run build
# Start the MCP server
npm run mcp

Advanced Usage

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

📚 Documentation

The single entry point is task - oriented navigation:

• doc/README.md — Where to start, task - based navigation
• doc/INDEX.md — Complete list of documents and links
• doc/QUICK-REFERENCE.md — Commands, examples, troubleshooting
• doc/GETTING-STARTED.md — Quick start
• doc/MCP-SETUP.md — Connect MCP in Cursor/Claude
• doc/DOCKER-SETUP.md — docker pull siniidrozd/mcp-comfy-ui-builder | docker - compose for MCP + ComfyUI
• Knowledge base: knowledge/README.md, doc/knowledge-base-usage-guide.md
• Workflow Builder: doc/workflow-builder.md — Templates, params, save/load, ComfyUI format
• Planning: ROADMAP.md, NEXT-STEPS.md, TODO.md — Current v2.3.x, next Phase 10 (QoL)
• Contributing: CONTRIBUTING.md
• MCP Registry: server.json and mcpName in package.json; see MCP Registry quickstart to publish after npm publish.

🔧 Technical Details

Requirements

• Node.js 18+

MCP Server (Cursor / Claude)

The 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 the project root, first build the project, then start the server:

npm run build
npm run mcp

Or without npm: node dist/mcp-server.js. The 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 the 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 the 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 (the 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