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": {}
    }
  }
}

2. Start Claude Code with MCP:

claude --mcp-config mcp_config.json

3. 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

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