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