BiodigitalJaz/comfyui-mcp

ComfyUI MCP Server - Production

A robust Model Context Protocol (MCP) server that provides Unity with reliable AI image generation through ComfyUI.

Features

🎨 Reliable Image Generation

• Queue-based completion detection (no timeouts)
• Multiple download fallback methods
• Production-grade error handling

🌸 Specialized Workflows

• General image generation with customizable parameters
• Flower texture generation optimized for Unity
• Support for seamless tileable textures

🔧 Production Ready

• Comprehensive logging and monitoring
• Configuration management with environment variables
• Robust error handling and recovery
• Performance statistics and health monitoring

🎮 Unity Integration

• Automatic Unity asset folder management
• PNG texture optimization
• Material-ready output format

Quick Start

Prerequisites

1. ComfyUI running on http://127.0.0.1:8188
2. Python 3.8+ with required packages
3. Unity project with Assets folder structure

Installation

1. Install dependencies:

   pip install mcp requests
   

2. Configure the MCP client to use this server:

   {
     "mcpServers": {
       "comfy": {
         "command": "python",
         "args": ["path/to/comfyui-mcp/server.py"],
         "cwd": "path/to/comfyui-mcp"
       }
     }
   }
   

3. Start using through Unity/Coplay!

Usage

Generate General Images

# Through MCP client
result = await mcp_client.call_tool("generate_image", {
    "client_id": "unity-client",
    "prompt": "beautiful landscape, sunset, high quality",
    "width": 1024,
    "height": 1024,
    "steps": 25,
    "cfg": 7.5
})

Generate Flower Textures

# Through MCP client
result = await mcp_client.call_tool("generate_flower_texture", {
    "client_id": "unity-client", 
    "flower_type": "rose",
    "seamless": True,
    "detail_level": "high"
})

Check Server Status

# Get server health and statistics
status = await mcp_client.call_tool("get_server_status", {
    "client_id": "unity-client"
})

Configuration

Environment Variables

Example Configuration

# Production settings
export COMFYUI_HOST="192.168.1.100"
export COMFYUI_PORT="8188"
export GENERATION_TIMEOUT="300"
export LOG_LEVEL="INFO"

# Development settings  
export COMFYUI_MCP_MODE="development"
export LOG_LEVEL="DEBUG"
export GENERATION_TIMEOUT="60"

Architecture

Core Components

1. ComfyUIClient - Handles all ComfyUI communication
2. WorkflowGenerator - Creates ComfyUI workflows for different use cases
3. FileManager - Manages Unity asset file operations
4. ImageGenerationService - High-level generation orchestration
5. MCP Server - Handles Model Context Protocol communication

Queue-Based Completion Detection

The server uses ComfyUI's queue API to reliably detect completion:

1. Submit workflow to ComfyUI queue
2. Monitor queue status (pending → running → completed)
3. When prompt disappears from queue, fetch results from history
4. Download and save generated images

This approach eliminates timeout issues and provides reliable completion detection.

Multiple Download Fallbacks

Images are downloaded using multiple fallback methods:

1. Standard method: /view?filename=X&subfolder=Y&type=Z
2. Direct method: /view?filename=X
3. Type-only method: /view?filename=X&type=output

This ensures compatibility with different ComfyUI configurations.

Monitoring & Debugging

Production Logs

The server provides comprehensive logging:

2025-01-24 14:21:35,123 - comfyui-mcp - INFO - Queued prompt abc123: beautiful landscape...
2025-01-24 14:21:45,456 - comfyui-mcp - INFO - Prompt abc123 completed
2025-01-24 14:21:46,789 - comfyui-mcp - INFO - Saved image: Assets/Textures/Generated/generated_1024x1024_2025-01-24_14-21-46.png (1234567 bytes)

Server Statistics

The server tracks performance metrics:

• Total requests processed
• Successful vs failed generations
• Server uptime
• ComfyUI connection status

Access via get_server_status tool.

Error Handling

The server provides detailed error information:

• ComfyUI connection issues
• Workflow submission failures
• Image download problems
• File system errors

All errors include context and suggested solutions.

Performance Tips

ComfyUI Optimization

1. Use appropriate models - Lighter models generate faster
2. Optimize steps - Fewer steps = faster generation
3. Batch processing - Queue multiple requests
4. Model caching - Keep models loaded in ComfyUI

Unity Integration

1. Texture compression - Enable appropriate compression in Unity
2. Mipmaps - Enable for seamless textures
3. Texture streaming - For large textures
4. Asset database refresh - Happens automatically

Troubleshooting

Common Issues

"ComfyUI is not running"

• Check ComfyUI is started and accessible at configured URL
• Verify firewall/network settings
• Check ComfyUI console for errors

"Generation timed out"

• Increase GENERATION_TIMEOUT environment variable
• Check ComfyUI queue for stuck jobs
• Verify model is loaded in ComfyUI

"No images found in outputs"

• Check ComfyUI workflow compatibility
• Verify model exists and is loaded
• Check ComfyUI console for workflow errors

"Cannot save to Unity folder"

• Check Unity project is open
• Verify write permissions to Assets folder
• Check disk space availability

Debug Mode

Enable debug logging:

export COMFYUI_MCP_MODE="development"
export LOG_LEVEL="DEBUG"

This provides detailed information about:

• Queue monitoring
• Image download attempts
• File operations
• Error details

Version History

• v1.0.0 - Production release with queue-based detection
• v0.9.x - Development versions with timeout fixes
• v0.8.x - Initial MCP server implementation

Community & Collaboration

Join our Discord community to collaborate, get help, and share your projects:

In our Discord server, you can:

• Get help with ComfyUI MCP integration
• Share your generated images and workflows
• Collaborate on new features and improvements
• Connect with other Unity AI developers
• Stay updated on the latest developments

Support

For issues and questions:

1. Check the troubleshooting section above
2. Enable debug logging for detailed information
3. Check ComfyUI server logs
4. Verify Unity project setup
5. Join our Discord community for real-time help

License

This ComfyUI MCP server is part of the Coplay AI development toolkit.