Comfy MCP Server
MCP server for comprehensive ComfyUI workflow automation, management, and image generation.
Overview
This server provides Claude Code (and other MCP clients) with full access to ComfyUI capabilities:
- System monitoring: Check server health, queue status, and history
- Workflow execution: Run saved workflows or execute custom workflow dicts
- Workflow management: Create, modify, save, and validate workflows
- Node discovery: List available nodes, models, and their parameters
- Image generation: Simple prompt-based generation or full workflow control
Key Features
✅ Schema-Validated Workflows
All generated workflows are validated against the ComfyUI v0.4 workflow schema, ensuring compatibility and correct execution. No more invalid workflow errors.
🎨 Beautiful Visual Layout
Programmatically generated workflows have coherent node positions with proper spacing and alignment. The built-in layout engine produces untangled, professional-looking workflows that are easy to read and modify in the ComfyUI editor.
Technical: Uses graph-based layout algorithms (NetworkX) to automatically position nodes, eliminating the typical spaghetti diagrams from programmatic workflow generation.
Prerequisites
- uv - Python package manager
- Running ComfyUI server (local or remote)
- Workflow files exported from ComfyUI (API format)
Installation
Via PyPI (Recommended)
# Run directly with uvx
uvx comfyui-easy-mcp
# Or install globally
uv pip install comfyui-easy-mcp
From Source
git clone https://github.com/IO-AtelierTech/comfyui-mcp.git
cd comfyui-mcp
uv sync
Configuration
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
COMFY_URL | No | http://localhost:8188 | ComfyUI server URL |
COMFY_URL_EXTERNAL | No | Same as COMFY_URL | External URL for image retrieval |
COMFY_WORKFLOWS_DIR | No | - | Directory for API format workflows (execution) |
COMFY_WORKFLOWS_UI_DIR | No | - | Directory for UI format workflows (editor) |
COMFY_WORKFLOW_JSON_FILE | No | - | Default workflow file for generate_image |
PROMPT_NODE_ID | No | - | Default prompt node ID for generate_image |
OUTPUT_NODE_ID | No | - | Default output node ID |
OUTPUT_MODE | No | file | Output mode: file (Image) or url (string URL) |
POLL_TIMEOUT | No | 60 | Max seconds to wait for workflow (1-300) |
POLL_INTERVAL | No | 1.0 | Seconds between status polls (0.1-10.0) |
Example Configuration
export COMFY_URL=http://localhost:8188
export COMFY_WORKFLOWS_DIR=/path/to/workflows-api # API format for execution
export COMFY_WORKFLOWS_UI_DIR=/path/to/workflows-ui # UI format for editor
export COMFY_WORKFLOW_JSON_FILE=/path/to/workflows-api/default.json
export PROMPT_NODE_ID=6
export OUTPUT_NODE_ID=9
export OUTPUT_MODE=file
Claude Desktop Config
{
"mcpServers": {
"ComfyUI": {
"command": "uvx",
"args": ["comfyui-easy-mcp"],
"env": {
"COMFY_URL": "http://localhost:8188",
"COMFY_WORKFLOWS_DIR": "/path/to/workflows-api",
"COMFY_WORKFLOWS_UI_DIR": "/path/to/workflows-ui",
"COMFY_WORKFLOW_JSON_FILE": "/path/to/workflows-api/default.json",
"PROMPT_NODE_ID": "6",
"OUTPUT_NODE_ID": "9"
}
}
}
}
Or use the pre-configured .mcp.json from comfyui-template.
Available Tools
System Tools
| Tool | Description |
|---|---|
get_system_stats() | Get ComfyUI server health: version, memory, device info |
get_queue_status() | Get current queue: running and pending jobs |
get_history(limit=10) | Get recent generation history (1-100 entries) |
cancel_current(prompt_id=None) | Interrupt current generation |
clear_queue(delete_ids=None) | Clear queue or delete specific items |
Discovery Tools
| Tool | Description |
|---|---|
list_nodes(filter=None) | List available ComfyUI nodes (optional filter) |
get_node_info(node_name) | Get detailed node info: inputs, outputs, parameters |
search_nodes(query) | Search nodes by name, type, or category |
list_models(folder="checkpoints") | List models in a folder |
list_model_folders() | List available model folder types |
list_embeddings() | List available embeddings |
list_extensions() | List loaded extensions (custom node packs) |
refresh_nodes() | Refresh cached node list from ComfyUI |
Workflow Management Tools
| Tool | Description |
|---|---|
list_workflows() | List available workflow files |
load_workflow(workflow_name) | Load a workflow from file |
save_workflow(workflow, name, format="ui") | Save workflow (format: "api" or "ui") |
create_workflow() | Create an empty workflow structure |
add_node(workflow, node_id, class_type, inputs) | Add a node to a workflow |
remove_node(workflow, node_id) | Remove a node from a workflow |
update_node_input(workflow, node_id, input_name, value) | Update a node's input |
validate_workflow(workflow) | Validate workflow structure and node types |
convert_workflow_to_ui(workflow) | Convert API format to UI/Litegraph format |
list_templates() | List available workflow templates |
get_workflow_template(template_name) | Get a pre-built workflow template |
generate_workflow_name(words=2) | Generate random funny workflow name |
Execution Tools
| Tool | Description |
|---|---|
generate_image(prompt) | Generate image using default workflow (simple interface) |
run_workflow(workflow_name, inputs=None, output_node_id=None) | Execute a saved workflow file |
execute_workflow(workflow, output_node_id) | Execute an arbitrary workflow dict |
submit_workflow(workflow) | Submit workflow without waiting (returns prompt_id) |
get_prompt_status(prompt_id) | Get status of a submitted prompt |
get_result_image(prompt_id, output_node_id) | Get result image from completed prompt |
Workflow Formats
ComfyUI uses two workflow formats. Understanding the difference is critical:
| Format | Structure | Use Case | Directory |
|---|---|---|---|
| API | {"node_id": {"class_type": "...", "inputs": {...}}} | MCP execution, automation | workflows-api/ |
| UI | {"nodes": [...], "links": [...], "version": ...} | ComfyUI editor only | workflows-ui/ |
IMPORTANT:
- Only API format workflows can be executed via MCP (
run_workflow(),execute_workflow()) - UI format workflows are for loading/editing in the ComfyUI web editor
- The MCP server will reject UI format workflows with an error if you try to execute them
Format Detection
The server automatically detects format by checking for "nodes" or "version" keys (UI format) vs "class_type" keys (API format).
Creating, Validating, and Saving Workflows
Recommended Workflow Process
# 1. CREATE: Start with empty workflow or template
wf = create_workflow()
# Or use a template:
wf = get_workflow_template("fal-flux-dev")
# 2. BUILD: Add nodes with explicit connections
wf = add_node(wf, "1", "LoadImage", {"image": "input.jpg"})
wf = add_node(wf, "2", "LumaImageToVideoNode", {
"prompt": "smooth camera motion",
"model": "ray-2",
"first_image": ["1", 0], # Connect to node "1", output index 0
"resolution": "1080p",
"duration": "5s"
})
wf = add_node(wf, "3", "SaveVideo_fal", {
"videos": ["2", 0],
"filename_prefix": "output"
})
# 3. VALIDATE: Check structure and node types before saving
validation = validate_workflow(wf)
# Returns: {"valid": true/false, "errors": [...], "warnings": [...]}
# 4. SAVE: Choose format based on purpose
# For MCP execution (API format):
save_workflow(wf, "my-workflow", format="api") # → workflows-api/my-workflow.json
# For ComfyUI editor (UI format):
save_workflow(wf, "my-workflow", format="ui") # → workflows-ui/my-workflow.json
Node Connections
Connections use the format ["source_node_id", output_index]:
# Connect node "1" output slot 0 to this input
wf = add_node(wf, "2", "CLIPTextEncode", {
"text": "my prompt",
"clip": ["1", 0] # ← Connection to node "1", first output
})
Discovering Node Parameters
Before adding a node, check its required inputs:
# Find available nodes
nodes = list_nodes(filter="Luma") # → ["LumaImageToVideoNode", ...]
# Get node details
info = get_node_info("LumaImageToVideoNode")
# Returns:
# {
# "input": {
# "required": {
# "prompt": ["STRING", {...}],
# "model": [["ray-2", "ray-flash-2"], {...}],
# "first_image": ["IMAGE"],
# ...
# },
# "optional": {...}
# },
# "output": ["VIDEO"],
# ...
# }
Validation Errors
Common validation issues:
| Error | Cause | Fix |
|---|---|---|
Unknown node type | Node class doesn't exist | Use list_nodes() to find correct name |
Missing required input | Required input not provided | Check get_node_info() for required inputs |
Invalid connection | Source node/output doesn't exist | Verify node IDs and output indices |
UI format detected | Trying to execute UI format | Use API format or re-export from ComfyUI |
Usage Examples
Simple Image Generation
# Using default workflow configuration
result = generate_image("a cyberpunk city at sunset")
Run a Named Workflow
# Execute saved workflow with custom inputs
result = run_workflow(
"flux-dev.json",
inputs={"6": {"text": "a forest landscape"}},
output_node_id="9"
)
Build and Execute Custom Workflow
# 1. Create empty workflow
wf = create_workflow()
# 2. Add nodes
wf = add_node(wf, "1", "CheckpointLoaderSimple", {
"ckpt_name": "flux-dev.safetensors"
})
wf = add_node(wf, "2", "CLIPTextEncode", {
"text": "beautiful sunset over mountains",
"clip": ["1", 1] # Connect to checkpoint's CLIP output
})
wf = add_node(wf, "3", "KSampler", {
"model": ["1", 0],
"positive": ["2", 0],
# ... other inputs
})
# 3. Validate before execution
validation = validate_workflow(wf)
if not validation.get("valid"):
print(f"Errors: {validation.get('errors')}")
# 4. Execute
result = execute_workflow(wf, output_node_id="9")
Async Workflow Submission
# Submit without waiting
submission = submit_workflow(workflow)
prompt_id = submission["prompt_id"]
# Check status later
status = get_prompt_status(prompt_id)
# Get result when ready
if status["completed"]:
image = get_result_image(prompt_id, "9")
Discover Available Nodes
# List all fal.ai nodes
nodes = list_nodes(filter="fal")
# Get details about a specific node
info = get_node_info("RemoteCheckpointLoader_fal")
Using fal.ai Connector
The ComfyUI-fal-Connector enables cloud GPU inference via fal.ai.
# 1. Verify fal.ai extension is loaded
extensions = list_extensions()
# Should include "ComfyUI-fal-Connector"
# 2. List available fal.ai nodes
fal_nodes = list_nodes(filter="fal")
# Returns: ["RemoteCheckpointLoader_fal", "StringInput_fal", "SaveImage_fal", ...]
# 3. Get node details
info = get_node_info("RemoteCheckpointLoader_fal")
# Shows available checkpoints: flux-dev, flux-schnell, sd3.5-large, etc.
# 4. Build a fal.ai workflow
wf = create_workflow()
wf = add_node(wf, "1", "RemoteCheckpointLoader_fal", {
"ckpt_name": "flux-dev"
})
wf = add_node(wf, "2", "StringInput_fal", {
"text": "a futuristic city at sunset, cyberpunk style"
})
wf = add_node(wf, "3", "CLIPTextEncode", {
"text": ["2", 0],
"clip": ["1", 1]
})
# ... add sampler, VAE decode, save image nodes
# 5. Execute on fal.ai cloud GPUs
result = execute_workflow(wf, output_node_id="9")
Environment Setup:
export FAL_KEY=your-fal-api-key
Architecture
comfy_mcp_server/
├── __init__.py # Entry point, FastMCP server
├── api.py # HTTP helpers, ComfyUI API functions
├── models.py # Pydantic models for type safety
├── settings.py # Configuration with pydantic-settings
├── compat.py # Version compatibility layer
└── tools/ # MCP tool implementations
├── system.py # System monitoring tools
├── discovery.py # Node/model discovery
├── workflow.py # Workflow management
└── execution.py # Workflow execution
Development
# Install dev dependencies
uv sync --all-extras
# Run linting
uv run ruff check src/
# Run tests (requires running ComfyUI)
uv run pytest tests/
# Format code
uv run ruff format src/
ComfyUI API Coverage
Target: ComfyUI 0.3.x - 0.4.x
| API Endpoint | Method | Description | Status |
|---|---|---|---|
/prompt | POST | Submit workflow for execution | ✅ Implemented |
/queue | GET | View running/pending jobs | ✅ Implemented |
/queue | POST | Clear queue / delete items | ✅ Implemented |
/history | GET | View generation history | ✅ Implemented |
/history/{id} | GET | Get specific job result | ✅ Implemented |
/history | POST | Delete history entries | ⚠️ Partial |
/interrupt | POST | Stop current generation | ✅ Implemented |
/object_info | GET | List all available nodes | ✅ Implemented |
/object_info/{node} | GET | Get node parameters/inputs | ✅ Implemented |
/models | GET | List model folders | ✅ Implemented |
/models/{folder} | GET | List models in folder | ✅ Implemented |
/system_stats | GET | Server health/resources | ✅ Implemented |
/view | GET | Retrieve generated images | ✅ Implemented |
/embeddings | GET | List available embeddings | ✅ Implemented |
/extensions | GET | List loaded extensions | ✅ Implemented |
/upload/image | POST | Upload image for workflows | ❌ Not implemented |
/upload/mask | POST | Upload mask for inpainting | ❌ Not implemented |
/free | POST | Free VRAM/memory | ❌ Not implemented |
/api/userdata/* | * | User data management | ❌ Not implemented |
Implementation Notes
- Partial: History deletion is not fully exposed as a tool
- Not implemented: Image/mask upload, memory management, and user data APIs are planned for future releases
Compatibility
- MCP Server Version: 0.2.0
- Minimum ComfyUI: 0.3.0
- Maximum Tested ComfyUI: 0.4.x
- Python: 3.10+
The server includes a compatibility layer that handles API differences between ComfyUI versions and provides graceful degradation.
License
MIT License - see LICENSE file.
Credits
Originally forked from @lalanikarim/comfyui-mcp.