PurlieuStudios/comfyui-mcp

ComfyUI MCP Server

AI-powered image generation for game development via ComfyUI and the Model Context Protocol

Overview

ComfyUI MCP Server is a Model Context Protocol (MCP) server that bridges ComfyUI's powerful workflow-based AI image generation with modern development workflows. Originally designed for Godot game development, it can be used with any MCP-compatible client to generate game assets, concept art, and visual content dynamically.

Key Features

• MCP Integration: Expose ComfyUI workflows as standardized MCP tools
• Python API Client: Full-featured async ComfyUI API client with type safety
• Workflow Templates: Pre-built templates for common game assets (characters, items, environments)
• Async Operations: Non-blocking generation with real-time progress updates via WebSockets
• Flexible Configuration: TOML files, environment variables, or Python code
• Type Safe: Full type hints with strict mypy validation
• Well Tested: Comprehensive test coverage with pytest
• Production Ready: Retry logic, error handling, and logging built-in

Use Cases

• Character Generation: NPC portraits, character sprites, concept art
• Item Icons: Unique item icons from text descriptions
• Environment Art: Background textures, tileable patterns, landscapes
• Dynamic Content: Procedural asset generation during gameplay
• Concept Art: Rapid visual prototyping and iteration
• Batch Processing: Generate multiple asset variations efficiently

Table of Contents

• Quick Start
• Installation
• Configuration
• Usage
  • MCP Server
  • Python API Client
• Workflow Templates
• Documentation
• Examples
• Development
• Troubleshooting
• Contributing
• License

Quick Start

Prerequisites

1. Python 3.10 or higher

   python --version  # Should be 3.10+
   

2. ComfyUI installed and running

   • Download: ComfyUI GitHub
   • Default URL: http://localhost:8188
   • Verify: Open http://localhost:8188 in your browser

3. Stable Diffusion models

   • Download models and place in ComfyUI's models/checkpoints/ directory
   • Recommended: Stable Diffusion 1.5 or 2.1 for game assets

Installation

# Clone the repository
git clone https://github.com/purlieu-studios/comfyui-mcp.git
cd comfyui-mcp

# Install the package
pip install -e .

# For development (includes testing and linting tools)
pip install -e ".[dev]"

# Verify installation
python -c "from comfyui_mcp import ComfyUIClient; print('Installation successful!')"

Basic Configuration

Option 1: Environment Variables (Recommended for getting started)

# Required
export COMFYUI_URL="http://localhost:8188"

# Optional
export COMFYUI_TIMEOUT="120.0"
export COMFYUI_OUTPUT_DIR="./generated_images"

Option 2: TOML Configuration File

Create comfyui.toml in your project root:

[comfyui]
url = "http://localhost:8188"
timeout = 120.0
output_dir = "./generated_images"

See for comprehensive configuration options.

Your First Generation

Using the Python API

import asyncio
from comfyui_mcp import ComfyUIClient, ComfyUIConfig, WorkflowPrompt

async def generate_image():
    # Configure the client
    config = ComfyUIConfig(url="http://localhost:8188")

    async with ComfyUIClient(config) as client:
        # Check ComfyUI server health
        if not await client.health_check():
            print("ComfyUI server is not responding!")
            return

        # Create a simple workflow
        workflow = WorkflowPrompt(
            prompt={
                "3": {
                    "class_type": "KSampler",
                    "inputs": {
                        "seed": 42,
                        "steps": 20,
                        "cfg": 7.0,
                        "sampler_name": "euler",
                        "scheduler": "normal",
                        "denoise": 1.0
                    }
                }
            }
        )

        # Submit and wait for completion
        prompt_id = await client.submit_workflow(workflow)
        print(f"Workflow submitted: {prompt_id}")

        result = await client.wait_for_completion(
            prompt_id=prompt_id,
            poll_interval=1.0,
            timeout=300.0
        )

        print(f"Generation complete! Result: {result}")

# Run the async function
asyncio.run(generate_image())

Using the MCP Server

1. Configure MCP Server

Add to your .mcp.json:

{
  "mcpServers": {
    "comfyui-mcp": {
      "command": "python",
      "args": ["-m", "comfyui_mcp.server"],
      "env": {
        "COMFYUI_URL": "http://localhost:8188",
        "COMFYUI_OUTPUT_DIR": "./generated_images"
      }
    }
  }
}

More Configuration Examples:

Complete .mcp.json configuration examples are available in :

See for detailed documentation of each configuration.

2. Use via Claude Code or MCP Client

# Via MCP client (example)
result = await mcp.call_tool(
    "generate_image",
    {
        "template": "character-portrait",
        "prompt": "fantasy elf warrior with detailed armor and glowing sword",
        "width": 512,
        "height": 512,
        "steps": 25,
        "seed": 12345
    }
)

Installation

From Source (Development)

# Clone the repository
git clone https://github.com/purlieu-studios/comfyui-mcp.git
cd comfyui-mcp

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

From PyPI (Coming Soon)

pip install comfyui-mcp

Dependencies

Core:

• Python 3.10+
• aiohttp - Async HTTP client for ComfyUI API
• pydantic - Data validation and settings management
• tomli - TOML configuration file parsing
• websockets - WebSocket support for real-time updates

Development:

• pytest - Testing framework
• pytest-asyncio - Async test support
• pytest-cov - Code coverage
• mypy - Static type checking
• ruff - Fast linting and formatting
• pre-commit - Git hooks for code quality

Configuration

ComfyUI MCP Server supports three configuration methods:

1. TOML Configuration File (Recommended for Projects)

Create comfyui.toml:

[comfyui]
# Required: ComfyUI server URL
url = "http://localhost:8188"

# Optional: API key for authentication (8+ characters)
# api_key = "your-api-key-here"

# Optional: Request timeout in seconds (1.0 - 3600.0)
timeout = 120.0

# Optional: Output directory for generated images
output_dir = "./generated_images"

Configuration file locations (searched in order):

1. ./comfyui.toml (current directory)
2. ~/.config/comfyui/comfyui.toml (user config)
3. /etc/comfyui/comfyui.toml (system-wide)

2. Environment Variables (Recommended for Deployment)

export COMFYUI_URL="http://localhost:8188"
export COMFYUI_API_KEY="your-api-key-min-8-chars"
export COMFYUI_TIMEOUT="120.0"
export COMFYUI_OUTPUT_DIR="./generated_images"

3. Python Code (Programmatic Configuration)

from comfyui_mcp import ComfyUIConfig, ComfyUIClient

# Direct instantiation
config = ComfyUIConfig(
    url="http://localhost:8188",
    api_key="your-api-key",
    timeout=120.0,
    output_dir="./generated_images"
)

# Load from environment
config = ComfyUIConfig.from_env()

# Use the config
async with ComfyUIClient(config) as client:
    await client.health_check()

Configuration Priority

When multiple methods are used:

1. Python code (highest priority)
2. Environment variables
3. TOML configuration file
4. Default values (lowest priority)

Example Configuration Files

Complete example configuration files are available in examples/config/:

Quick start:

# Copy minimal config to get started
cp examples/config/comfyui.minimal.toml comfyui.toml

# Or use a specific environment
cp examples/config/comfyui.dev.toml comfyui.toml

See for comprehensive configuration documentation.

Usage

MCP Server Usage

The MCP server exposes ComfyUI functionality as standardized MCP tools.

Available MCP Tools

Example: Generate Image Tool

{
  "tool": "generate_image",
  "arguments": {
    "template": "character-portrait",
    "prompt": "cyberpunk hacker, neon lights, detailed face",
    "negative_prompt": "blurry, low quality",
    "width": 512,
    "height": 768,
    "steps": 30,
    "cfg_scale": 7.5,
    "seed": 42
  }
}

Starting the MCP Server

# Via Python module
python -m comfyui_mcp.server

# Or with custom configuration
COMFYUI_URL="http://localhost:8188" python -m comfyui_mcp.server

Python API Client

Direct programmatic access to ComfyUI API.

Basic Usage

from comfyui_mcp import ComfyUIClient, ComfyUIConfig

async def main():
    config = ComfyUIConfig(url="http://localhost:8188")

    async with ComfyUIClient(config) as client:
        # Health check
        is_healthy = await client.health_check()
        print(f"ComfyUI Status: {'Online' if is_healthy else 'Offline'}")

        # Get system info
        system_stats = await client.get_system_stats()
        print(f"System: {system_stats}")

Submitting Workflows

from comfyui_mcp import WorkflowPrompt

async def generate():
    config = ComfyUIConfig.from_env()

    async with ComfyUIClient(config) as client:
        workflow = WorkflowPrompt(
            prompt={
                "1": {
                    "class_type": "CheckpointLoaderSimple",
                    "inputs": {"ckpt_name": "sd_v1-5.safetensors"}
                },
                "2": {
                    "class_type": "CLIPTextEncode",
                    "inputs": {
                        "text": "beautiful landscape, mountains, sunset",
                        "clip": ["1", 0]
                    }
                }
                # ... more nodes
            }
        )

        # Submit workflow
        prompt_id = await client.submit_workflow(workflow)

        # Wait for completion (with polling)
        result = await client.wait_for_completion(
            prompt_id=prompt_id,
            poll_interval=2.0,  # Check every 2 seconds
            timeout=300.0        # Timeout after 5 minutes
        )

        return result

Queue Management

async def manage_queue():
    async with ComfyUIClient(config) as client:
        # Get queue status
        queue = await client.get_queue()
        print(f"Queue size: {queue['queue_running']}")

        # Cancel specific workflow
        await client.cancel_workflow(prompt_id="abc-123")

        # Clear entire queue (careful!)
        await client.interrupt()

Retrieving Generated Images

async def download_images(prompt_id: str):
    async with ComfyUIClient(config) as client:
        # Get workflow result
        history = await client.get_history(prompt_id)

        # Extract image filenames
        for node_id, output in history["outputs"].items():
            if "images" in output:
                for image in output["images"]:
                    # Download image
                    image_data = await client.download_image(
                        filename=image["filename"],
                        subfolder=image.get("subfolder", ""),
                        folder_type=image.get("type", "output")
                    )

                    # Save to file
                    with open(f"./output/{image['filename']}", "wb") as f:
                        f.write(image_data)

Error Handling

from comfyui_mcp.exceptions import (
    ComfyUIError,
    ConnectionError,
    WorkflowExecutionError,
    TimeoutError
)

async def safe_generation():
    try:
        async with ComfyUIClient(config) as client:
            result = await client.submit_workflow(workflow)

    except ConnectionError as e:
        print(f"Cannot connect to ComfyUI: {e}")
    except WorkflowExecutionError as e:
        print(f"Workflow failed: {e}")
    except TimeoutError as e:
        print(f"Generation timed out: {e}")
    except ComfyUIError as e:
        print(f"ComfyUI error: {e}")

See for complete API documentation.

Workflow Templates

Pre-built workflow templates for common game asset types.

Available Templates

Using Templates

from comfyui_mcp import WorkflowTemplateManager

# Load template manager
manager = WorkflowTemplateManager(templates_dir="./workflows")

# List available templates
templates = manager.list_templates()
for template in templates:
    print(f"{template.name}: {template.description}")

# Load and customize template
template = manager.load_template("character-portrait")
workflow = template.instantiate(
    prompt="fantasy wizard with blue robes",
    seed=12345,
    steps=25
)

# Submit to ComfyUI
async with ComfyUIClient(config) as client:
    prompt_id = await client.submit_workflow(workflow)

Creating Custom Templates

See for template creation guide.

Documentation

Comprehensive documentation is available in the docs/ directory:

• - Complete Python API documentation

  • ComfyUIClient methods and parameters
  • Pydantic models and data structures
  • Exception handling
  • Type hints and examples

• - Configuration options and best practices

  • TOML file format and schema
  • Environment variables
  • Configuration priority
  • Example configurations

• - ComfyUI REST API patterns

  • API endpoints and methods
  • Workflow structure
  • Queue management
  • WebSocket integration

• - Complete MCP tool reference and usage guide

  • All 5 MCP tools documented
  • Integration patterns and examples
  • Best practices and troubleshooting

• - Comprehensive guide to creating ComfyUI workflows

  • Understanding workflow structure and node system
  • Creating workflows from scratch
  • Parameter substitution and templates
  • Advanced techniques (LoRA, ControlNet, batching)
  • Integration with MCP server
  • Complete examples for characters, items, and environments

• - Complete workflow template system documentation

  • Template structure and file format
  • Creating and using templates
  • Built-in templates (character, item, environment, pixel art)
  • Parameter substitution engine
  • WorkflowTemplateManager usage
  • Best practices and advanced topics
  • Complete examples and troubleshooting

• (coming soon) - Godot plugin and examples

Examples

Practical examples are available in the examples/ directory:

Example Projects

• - Generate RPG character portraits
• - Batch generate inventory icons
• - Create tileable background textures
• - Live generation in Godot engine
• - Generate sprite variations

Running Examples

# Set configuration
export COMFYUI_URL="http://localhost:8188"

# Run character portrait example
python examples/character_portrait.py

# Run batch item icon generation
python examples/item_icons.py --count 10 --prompt "fantasy sword"

Development

Setup Development Environment

# Clone repository
git clone https://github.com/purlieu-studios/comfyui-mcp.git
cd comfyui-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install with development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage report
pytest tests/ -v --cov=comfyui_mcp --cov-report=term-missing

# Run specific test file
pytest tests/test_client.py -v

# Run tests matching pattern
pytest tests/ -v -k "test_workflow"

Code Quality Checks

# Type checking (strict mode)
mypy src/

# Linting
ruff check src/ tests/

# Format code
ruff format src/ tests/

# Run all quality checks
pre-commit run --all-files

Project Structure

comfyui-mcp/
├── src/
│   └── comfyui_mcp/           # Main package
│       ├── __init__.py        # Public API exports
│       ├── server.py          # MCP server implementation
│       ├── comfyui_client.py  # ComfyUI API client
│       ├── models.py          # Pydantic data models
│       ├── config.py          # Configuration management
│       ├── exceptions.py      # Custom exceptions
│       └── utils.py           # Utility functions
├── tests/                     # Test suite
│   ├── test_client.py         # Client tests
│   ├── test_models.py         # Model validation tests
│   ├── test_config.py         # Configuration tests
│   └── fixtures/              # Test fixtures
├── examples/                  # Example scripts
│   ├── character_portrait.py
│   ├── item_icons.py
│   └── godot/                 # Godot integration
├── workflows/                 # Workflow templates
│   ├── character-portrait.json
│   ├── item-icon.json
│   └── environment-texture.json
├── docs/                      # Documentation
│   ├── API.md
│   ├── CONFIGURATION.md
│   └── COMFYUI_API.md
├── .github/workflows/         # CI/CD
│   └── ci.yml
├── pyproject.toml             # Package configuration
├── README.md                  # This file
├── CLAUDE.md                  # AI assistant context
└── LICENSE                    # MIT License

Contributing

We welcome contributions! Please see for guidelines.

Quick contribution checklist:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Write tests for your changes
4. Ensure all tests pass (pytest tests/)
5. Run type checking (mypy src/)
6. Run linting (ruff check src/ tests/)
7. Format code (ruff format src/ tests/)
8. Commit changes (git commit -m 'feat: add amazing feature')
9. Push to branch (git push origin feature/amazing-feature)
10. Open a Pull Request

Troubleshooting

Common Issues

ComfyUI Server Connection Failed

Problem: ConnectionError: Cannot connect to ComfyUI server at http://localhost:8188

Solutions:

1. Verify ComfyUI is running: Open http://localhost:8188 in browser
2. Check URL configuration: Ensure COMFYUI_URL is correct
3. Check firewall settings: Allow connections on port 8188
4. Try explicit localhost: Use http://127.0.0.1:8188 instead of http://localhost:8188

# Test connection
from comfyui_mcp import ComfyUIClient, ComfyUIConfig

async def test_connection():
    config = ComfyUIConfig(url="http://127.0.0.1:8188")
    async with ComfyUIClient(config) as client:
        is_healthy = await client.health_check()
        print(f"Connection: {'✓' if is_healthy else '✗'}")

Workflow Execution Timeout

Problem: TimeoutError: Workflow execution exceeded timeout of 120.0 seconds

Solutions:

1. Increase timeout in configuration:

   [comfyui]
   timeout = 300.0  # 5 minutes
   

2. Reduce workflow complexity (fewer steps, lower resolution)

3. Check ComfyUI server logs for errors

4. Ensure models are downloaded and accessible

Module Import Errors

Problem: ModuleNotFoundError: No module named 'comfyui_mcp'

Solutions:

1. Reinstall package: pip install -e .
2. Activate virtual environment: source venv/bin/activate
3. Check Python path: echo $PYTHONPATH

Type Checking Errors

Problem: mypy reports type errors

Solutions:

1. Update type stubs: pip install --upgrade types-all
2. Check mypy configuration in pyproject.toml
3. Use # type: ignore for false positives (sparingly)

Debug Mode

Enable debug logging:

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Now all ComfyUI MCP operations will log debug information

Getting Help

• GitHub Issues: Report bugs or request features
• GitHub Discussions: Ask questions and share ideas
• Documentation:

Roadmap

See GitHub Milestones for upcoming features.

Planned Features

• Phase 1: Foundation (Current)

  • ✅ ComfyUI API client
  • ✅ MCP server implementation
  • ✅ Basic workflow templates
  • ✅ Configuration system
  • ✅ Comprehensive documentation

• Phase 2: Advanced Features (Next)

  • WebSocket support for real-time progress
  • Advanced workflow template system
  • Image post-processing pipeline
  • Generation caching
  • Batch processing optimization

• Phase 3: Godot Integration (Future)

  • Godot GDScript helper library
  • Godot plugin for ComfyUI integration
  • Editor tools for workflow testing
  • Asset pipeline integration

• Phase 4: Production Enhancements (Future)

  • Authentication and API key support
  • Rate limiting and queue management
  • Monitoring and metrics
  • Docker containerization
  • Kubernetes deployment support

License

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

Acknowledgments

• ComfyUI - Powerful workflow-based Stable Diffusion UI by comfyanonymous
• Godot Engine - Open-source game engine
• Model Context Protocol - Universal AI integration standard by Anthropic
• Pydantic - Data validation using Python type hints
• Ruff - Fast Python linter and formatter

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Documentation:

Status: Alpha - Active Development

Built with ❤️ by Purlieu Studios