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