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 docs/CONFIGURATION.md 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 examples/mcp/: