ComfyUI MCP Server

DSL-first workflow management for ComfyUI via Model Context Protocol (MCP)

A production-ready MCP server that enables AI agents to manage ComfyUI workflows using a human-readable Domain Specific Language (DSL). The core design philosophy is DSL-first: agents work entirely in DSL format, with JSON conversion happening transparently.

Quick Start

Installation

pip install comfy-mcp

Usage with Claude Code

1. Create MCP configuration:

{
  "mcpServers": {
    "comfyui-workflows": {
      "command": "comfy-mcp",
      "args": [],
      "env": {}
    }
  }
}

1. Start Claude Code with MCP:

claude --mcp-config mcp_config.json

1. Use in conversation:

"Execute this workflow: [paste DSL]"
"List workflows in examples directory"
"Show ComfyUI queue status"

Features

DSL-First Design

• Agents work entirely in human-readable DSL
• Automatic JSON DSL conversion
• No need to think about format conversion

File Operations

• read_workflow - Auto-converts JSON to DSL
• write_workflow - Saves DSL as JSON/DSL
• list_workflows - Discovers workflow files
• validate_workflow - DSL syntax validation
• get_workflow_info - Workflow analysis

Execution Operations

• execute_workflow - Run DSL workflows on ComfyUI
• get_job_status - Monitor execution & download images
• list_comfyui_queue - View ComfyUI queue status

DSL Syntax Example

## Model Loading

checkpoint: CheckpointLoaderSimple
  ckpt_name: sd_xl_base_1.0.safetensors

## Text Conditioning

positive: CLIPTextEncode
  text: a beautiful landscape, detailed, photorealistic
  clip: @checkpoint.clip

negative: CLIPTextEncode
  text: blurry, low quality
  clip: @checkpoint.clip

## Generation

latent: EmptyLatentImage
  width: 1024
  height: 1024

sampler: KSampler
  model: @checkpoint.model
  positive: @positive.conditioning
  negative: @negative.conditioning
  latent_image: @latent.latent
  seed: 42
  steps: 20

## Output

decode: VAEDecode
  samples: @sampler.latent
  vae: @checkpoint.vae

save: SaveImage
  images: @decode.image
  filename_prefix: output

Architecture

        
   AI Agent        MCP Server    ComfyUI    
   (Claude)                               Server    
        
                                                  
          DSL Workflows          JSON API         
                                                  
                                                  
   Natural Language  DSL Parser  JSON Converter

Key Components:

• DSL Parser: Converts human-readable DSL to Abstract Syntax Tree
• JSON Converter: Bidirectional conversion between DSL and ComfyUI JSON
• MCP Server: Exposes tools via Model Context Protocol
• Execution Engine: Integrates with ComfyUI API for workflow execution

Documentation

Core Classes

• DSLParser: Parse DSL text into Abstract Syntax Tree
• DslToJsonConverter: Convert DSL AST to ComfyUI JSON
• JsonToDslConverter: Convert ComfyUI JSON to DSL AST

MCP Tools

Development

Setup

git clone https://github.com/christian-byrne/comfy-mcp.git
cd comfy-mcp
pip install -e ".[dev]"
pre-commit install

Testing

# Run all tests
pytest

# Run with coverage
pytest --cov=comfy_mcp --cov-report=html

# Run specific test types
pytest -m unit
pytest -m integration
pytest -m "not slow"

Code Quality

# Format code
black .

# Lint code  
ruff check .

# Type checking
mypy comfy_mcp

Documentation

cd docs
make html

Configuration

Environment Variables

• COMFYUI_SERVER: ComfyUI server address (default: 127.0.0.1:8188)
• MCP_DEBUG: Enable debug logging
• MCP_LOG_LEVEL: Set log level (DEBUG, INFO, WARNING, ERROR)

ComfyUI Setup

1. Install ComfyUI
2. Start server: python main.py --listen 0.0.0.0
3. Ensure models are installed in models/checkpoints/

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Workflow

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make changes and add tests
4. Run tests and linting: pytest && black . && ruff check .
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• ComfyUI - Amazing stable diffusion GUI
• FastMCP - Excellent MCP framework
• Anthropic - Model Context Protocol specification

Roadmap

• v0.2.0: Enhanced DSL features (templates, macros)
• v0.3.0: Web UI for workflow management
• v0.4.0: Git integration for workflow versioning
• v0.5.0: ComfyUI node discovery and documentation
• v1.0.0: Production deployment features

Built with for the ComfyUI and AI automation community