comfyui-mcp-server

ComfyUI MCP Server

A full-featured implementation of the Model Context Protocol (MCP) for ComfyUI, enabling AI agents to generate and manipulate images using a standardized API.

📋 Table of Contents

• Introduction
• Features
• Installation
• Quick Start
• Usage Examples
• Project Structure
• API Reference
• Advanced Usage
• Troubleshooting
• Contributing
• License

🌟 Introduction

ComfyUI MCP Server bridges the gap between AI agents and image generation by implementing the Model Context Protocol (MCP) for ComfyUI.

The Model Context Protocol is a standardized way for AI agents to discover and interact with tools through rich metadata and schema information. This implementation allows any AI assistant to easily generate and manipulate images using Stable Diffusion models through ComfyUI.

🔍 What is MCP? The Model Context Protocol (MCP) standardizes how AI agents communicate with external tools, enabling consistent interfaces with rich metadata and capabilities descriptions.

🚀 Features

• Full MCP Protocol Implementation

  • Tool discovery with metadata and schemas
  • Session and context management
  • Real-time communication

• Rich Image Generation Capabilities

  • Text-to-image (txt2img)
  • Image-to-image transformation (img2img)
  • Inpainting
  • ControlNet support
  • LoRA model integration

• Advanced Infrastructure

  • Job queue with priority support
  • Progress tracking and real-time updates
  • Authentication and rate limiting
  • Session persistence
  • Database backend for job history

💻 Installation

Prerequisites

• Python 3.10+
• ComfyUI installed and running
• 4GB+ RAM recommended
• CUDA-compatible GPU recommended (but not required)

Option 1: Clone and Install

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

# Install dependencies
pip install -r requirements.txt

# Run the installation script
python install.py --create-venv

Option 2: Manual Setup

# Create and prepare project directory
mkdir comfyui-mcp-server
cd comfyui-mcp-server

# Copy the source files into this directory

# Install required packages
pip install websockets requests aiohttp aiohttp_cors aiohttp_session cryptography aiosqlite mcp

🏃‍♂️ Quick Start

Step 1: Start ComfyUI

Make sure to start ComfyUI first before running the MCP server:

cd /path/to/ComfyUI
python main.py --port 8188

Verify ComfyUI is running by accessing http://localhost:8188 in your browser.

Step 2: Start the MCP Server

cd /path/to/comfyui-mcp-server

# Run with default settings
python mcp_integration.py

# Or run with custom config
python mcp_integration.py --config my_config.json

Step 3: Test the Connection

Run the MCP client to verify everything is working:

# Check available tools
python mcp_client.py --action manifest

# Generate a test image
python mcp_client.py --action generate --prompt "a dog wearing sunglasses"

📝 Usage Examples

Basic Image Generation

Generate an image from a text prompt:

python mcp_client.py --action generate --prompt "a cat in space" --width 768 --height 512

Image-to-Image Transformation

Transform an existing image based on a prompt:

python mcp_client.py --action img2img --prompt "watercolor painting" --image input.jpg --strength 0.75

List Available Models

See what models are available to use:

python mcp_client.py --action list-models

Using in Python Scripts

import asyncio
from mcp_client import MCPClient

async def generate_images():
    client = MCPClient()
    await client.connect()
    
    # Generate an image
    result = await client.generate_image(
        prompt="an astronaut riding a horse on mars",
        width=768,
        height=512
    )
    
    # Get job ID and wait for completion
    job_id = result["job_id"]
    await client.subscribe_to_job(job_id)
    final_status = await client.wait_for_job_completion(job_id)
    
    # Print result
    print(f"Generated image: {final_status['result']['image_url']}")
    
    await client.disconnect()

if __name__ == "__main__":
    asyncio.run(generate_images())

📂 Project Structure

comfyui-mcp-server/
├── mcp_protocol.py     # Core MCP protocol implementation
├── mcp_integration.py  # MCP server implementation
├── mcp_client.py       # MCP client
├── job_queue.py        # Job queue system
├── db_manager.py       # Database management
├── model_manager.py    # Model management
├── workflow_analyzer.py # Workflow analysis
├── auth.py             # Authentication & authorization
├── progress_tracker.py # Progress tracking
├── config.json         # Configuration file
├── workflows/          # Workflow definition files
│   ├── basic_api_test.json
│   ├── img2img.json
│   ├── inpaint.json
│   └── simple.json
├── data/               # Data storage folder (created on run)
└── logs/               # Log files (created on run)

📚 API Reference

Available MCP Tools

Configuration Options

The config.json file contains these key settings:

{
  "comfyui_url": "http://localhost:8188",
  "comfyui_ws_url": "ws://localhost:8188/ws",
  "mcp_server_host": "localhost",
  "mcp_server_port": 9000,
  "enable_auth": false,
  "max_concurrent_jobs": 2
}

🔧 Advanced Usage

Setting Up Authentication

1. Edit config.json to enable authentication:

   {
     "enable_auth": true,
     "auth_config_path": "auth_config.json"
   }
   

2. Create or modify auth_config.json:

   {
     "default_client": {
       "api_key": "YOUR_API_KEY_HERE",
       "permissions": ["*"],
       "rate_limit": {
         "rate": 5,
         "per": 60,
         "burst": 10
       }
     }
   }
   

3. Use the API key in client requests:

   python mcp_client.py --api-key YOUR_API_KEY_HERE --action generate --prompt "test"
   

Customizing Workflows

1. Export a workflow from ComfyUI in API format (enable dev mode in settings)
2. Save the JSON file to the workflows/ directory
3. Use it with the client:

   python mcp_client.py --action generate --prompt "test" --workflow my_custom_workflow
   

❓ Troubleshooting

Connection Issues

Problem: Cannot connect to ComfyUI Solution: Ensure ComfyUI is running and accessible at the configured URL:

curl http://localhost:8188/system_stats

Problem: MCP server won't start Solution: Check logs in the logs directory and verify port 9000 is available:

lsof -i :9000    # On Linux/Mac
# or
netstat -ano | findstr :9000    # On Windows

Image Generation Issues

Problem: Generation fails with workflow errors Solution:

• Check that ComfyUI has the required models installed
• Update the workflow JSON to match your ComfyUI installation
• Verify seed values are positive integers
• Check JSON encoding in workflow files

Problem: Timeout during image generation Solution: Increase the timeout value in advanced_comfyui_client.py:

max_attempts = 300  # 5 minutes

🤝 Contributing

Contributions are welcome! Here are some ways to get involved:

1. Report bugs and request features by opening Issues
2. Submit Pull Requests for bug fixes or enhancements
3. Create new workflows for different generation tasks
4. Improve documentation to help new users

Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

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

Made with ❤️ for AI and image generation

Report Bug • Request Feature