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

Create MCP configuration:

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

Start Claude Code with MCP:

claude --mcp-config mcp_config.json

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

Tool	Description	Example
`read_workflow`	Read and convert workflows to DSL	`read_workflow("workflow.json")`
`write_workflow`	Write DSL to disk as JSON/DSL	`write_workflow("output.json", dsl)`
`list_workflows`	Find workflow files	`list_workflows("./workflows")`
`validate_workflow`	Check DSL syntax	`validate_workflow(dsl_content)`
`get_workflow_info`	Analyze structure	`get_workflow_info(dsl_content)`
`execute_workflow`	Run on ComfyUI	`execute_workflow(dsl_content)`
`get_job_status`	Monitor execution	`get_job_status(prompt_id)`
`list_comfyui_queue`	View queue	`list_comfyui_queue()`

🛠️ 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

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

🤝 Contributing

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

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature-name
Make changes and add tests
Run tests and linting: pytest && black . && ruff check .
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