comfyui-workflow-editor-mcp

A lightweight MCP (Model Context Protocol) server that bridges AI agents (like Cursor, Claude, etc.) with a local ComfyUI instance. It enables AI agents to generate and iteratively refine images, audio, and video through conversational tool calls — with a graph-based workflow editor for safe, validated modifications.

Features

• Workflow Graph Editor: Safe, validated editing of ComfyUI workflows as directed graphs
  • Add, remove, replace, and insert nodes with automatic type-checking and cycle detection
  • Search available node types from the ComfyUI /object_info catalog
  • Validate workflows before execution (type mismatches, cycles, orphans, missing inputs)
  • Compare workflows, convert between API and frontend formats, generate workflows from templates

Quick Start

Option 1: Via npx (for MCP clients)

No local clone needed. Add to your MCP client configuration (Cursor, Claude, etc.):

"comfyui": {
  "command": "npx",
  "args": ["-y", "comfyui-workflow-editor-mcp"],
  "env": {
    "COMFYUI_URL": "http://localhost:8188",
    "COMFY_MCP_WORKFLOW_DIR": "/path/to/workflows",
    "COMFY_MCP_ASSET_TTL_HOURS": "24"
  }
}

Note: ComfyUI must be running at COMFYUI_URL before the MCP client connects.

Option 2: Local development

git clone https://github.com/yar3333/comfyui-workflow-editor-mcp.git
cd comfyui-workflow-editor-mcp
npm install
npm run build

Then start:

Command	Mode
npm start	stdio (for MCP clients)
npm run dev	stdio with ts-node

Configuration

Environment Variables

Variable	Description	Default
COMFYUI_URL	ComfyUI base URL	http://localhost:8188
COMFY_MCP_WORKFLOW_DIR	Path to workflow directory	./workflows
COMFY_MCP_ASSET_TTL_HOURS	Asset time-to-live in hours	24

API Tools

Generation Tools

Tool	Description
<workflows>	Available workflows automatically published as tools
regenerate	Regenerate a previously generated asset

Viewing Tools

Tool	Description
view_image	View a generated image inline in chat

Job Management Tools

Tool	Description
get_queue_status	Get current queue status from ComfyUI
get_job	Get job status by prompt_id
wait_for_job	Wait for a job to complete with timeout
list_assets	List generated assets with optional filtering
get_asset_metadata	Get full metadata for a specific asset
cancel_job	Cancel a running job by prompt_id

Configuration Tools

Tool	Description
list_checkpoint_models	List available checkpoint models from ComfyUI
list_unet_models	List available UNet models in standard (safetensors) format
list_unet_gguf_models	List available UNet models in GGUF format

Workflow Tools

Tool	Description
list_workflows	List available workflows in the workflow directory
run_workflow	Run a specific workflow with parameter overrides

Workflow Graph Editor Tools

Graph-based tools for safe, validated editing of ComfyUI workflows. All mutations validate type compatibility, detect cycles, and report orphan nodes.

Tool	Description
get_workflow_graph	Get workflow structure as a graph with nodes, links, chains
search_node_types	Search available node types from the ComfyUI catalog
get_node_info	Get detailed schema for a node type (inputs, outputs, defaults)
add_node	Add a node with validation (type-check, cycle detection)
remove_node	Remove a node, reporting affected connections and orphans
connect_nodes	Create a connection between node outputs and inputs
disconnect_node_input	Disconnect an input from a node
set_node_input	Change a primitive input value on a node
insert_node	Insert a node into an existing link (break-and-reconnect)
replace_node	Replace a node type, preserving compatible connections
validate_workflow	Full validation: types, cycles, orphans, missing inputs
find_connection_path	Find the dependency path between two nodes
build_basic_workflow	Generate a workflow from a template (txt2img, img2img, etc.)
convert_workflow_format	Convert between ComfyUI API format and frontend JSON format
diff_workflows	Compare two workflows, showing added/removed/modified nodes

Workflow Graph Editor

The workflow graph editor represents ComfyUI workflows as directed graphs, enabling safe modifications with automatic validation.

How It Works

• WorkflowGraph — in-memory graph representation of a workflow (nodes, connections, execution order)
• NodeTypesCatalog — cached catalog of available node types loaded from ComfyUI's /object_info API
• Validation rules — every mutation is checked against the same rules ComfyUI uses internally:

Check	Description
Required inputs	All mandatory inputs must be provided
Link targets	Links reference existing nodes and valid slot indices
Type compatibility	Output types match input type expectations (supports unions and wildcards)
Cycle detection	DFS-based cycle detection prevents invalid dependency graphs
Orphan detection	Nodes unreachable from any output node are flagged
Output node check	At least one output node (SaveImage, SaveAudio, etc.) must exist

Built-in Templates

build_basic_workflow supports the following templates:

Template	Description	Nodes
txt2img_basic	Basic text-to-image	CheckpointLoader, 2×CLIPTextEncode, EmptyLatent, KSampler, VAEDecode, SaveImage
img2img_basic	Image-to-image	CheckpointLoader, LoadImage, VAEEncode, 2×CLIPTextEncode, KSampler, VAEDecode, SaveImage
txt2img_controlnet	Text-to-image + ControlNet	Basic + ControlNetLoader, LoadImage, ControlNetApply
txt2img_sdxl	SDXL text-to-image	CheckpointLoader, CLIPTextEncode (4×), EmptyLatent, KSampler (2×), VAEDecode, SaveImage
upscale_basic	Upscale pipeline	CheckpointLoader, ImageUpscaleWithModel, VAEEncode, KSampler, VAEDecode, SaveImage

Format Conversion

ComfyUI uses two JSON formats:

• API format — flat {node_id: NodeData} map used by the backend (what the MCP server works with)
• Frontend format — structured {nodes, links, groups} format exported from the ComfyUI UI

Use convert_workflow_format to convert between them.

Workflow System

Workflows are stored as JSON files in the workflows/ directory. The system automatically discovers workflows and exposes them as MCP tools. Parameters are defined using the PARAM_* placeholder system:

• PARAM_INT_SEED - Integer parameter for seed
• PARAM_FLOAT_CFG - Float parameter for CFG scale
• PARAM_STR_SAMPLER_NAME - String parameter for sampler name
• PARAM_PROMPT - String parameter for prompt

Test

Prerequisites: ComfyUI running at http://localhost:8188, server built and started.

# Run the test client
npx ts-node test_client.ts

# With custom prompt
npx ts-node test_client.ts -p "a beautiful sunset over mountains"

# Run unit tests
npm test

Project Structure

comfyui-workflow-editor-mcp/
├── src/
│   ├── comfyui_client.ts        # HTTP client for ComfyUI API
│   ├── asset_processor.ts       # Image processing utilities
│   ├── server.ts                # Main entry point
│   ├── models/                  # Data models
│   │   ├── asset.ts
│   │   ├── workflow.ts
│   │   ├── workflow_graph.ts    # WorkflowGraph — in-memory graph representation
│   │   └── node_types.ts        # NodeTypeSchema and related interfaces
│   ├── managers/                # Manager classes
│   │   ├── workflow_manager.ts
│   │   ├── asset_registry.ts
│   │   └── node_types_catalog.ts # NodeTypesCatalog — cached /object_info catalog
│   └── tools/                   # MCP tool implementations
│       ├── helpers.ts
│       ├── generation.ts
│       ├── asset.ts
│       ├── job.ts
│       ├── configuration.ts
│       ├── workflow.ts          # list_workflows, run_workflow
│       └── workflow_edit.ts     # Graph editor tools (add, remove, connect, validate, etc.)
├── workflows/                   # Workflow JSON files
├── test_client.ts               # Test client
├── package.json
├── tsconfig.json
└── README.md

License

MIT

Author

@yar3333