MCP ComfyUI Flux

# MCP Setup for Claude Desktop ## Quick Setup 1. **Ensure containers are running:** ```bash docker compose -p mcp-comfyui-flux up -d # Or use the build script ./build.sh --start ``` 2. **Add to Claude Desktop configuration:** ### Windows (WSL2) Edit `%APPDATA%\Claude\claude_desktop_config.json`: ```json { "mcpServers": { "comfyui-flux": { "command": "wsl.exe", "args": [ "bash", "-c", "cd /home/YOUR_USERNAME/projects/tools/mcp-comfyui-flux && docker exec -i mcp-comfyui-flux-mcp-server-1 node /app/src/index.js" ] } } } ``` ### Linux/macOS Edit `~/.config/claude/claude_desktop_config.json`: ```json { "mcpServers": { "comfyui-flux": { "command": "docker", "args": [ "exec", "-i", "mcp-comfyui-flux-mcp-server-1", "node", "/app/src/index.js" ] } } } ``` 3. **Restart Claude Desktop** to load the MCP server ## Available Tools ### generate_image Generate high-quality images using FLUX schnell fp8 model (optimized for 4-step generation) **Parameters:** - `prompt` (required): Text description of the image - `negative_prompt`: Things to avoid in the image (default: '') - `width`: Image width (default: 1024) - `height`: Image height (default: 1024) - `steps`: Number of diffusion steps (default: 4 - optimized for schnell) - `cfg_scale`: Guidance scale (default: 1.0 - optimal for schnell) - `seed`: Random seed (-1 for random) - `sampler_name`: Sampling method (default: 'euler') - `scheduler`: Scheduler type (default: 'simple') - `batch_size`: Number of images to generate (default: 1, max: 8) **Example prompts:** ``` Generate an image of a "cyberpunk city at night, neon lights, rain, reflections" Create a "portrait of a wizard, detailed face, magical aura, fantasy art style" Make a batch of 4 images of "majestic mountain landscape at sunset" ``` ### upscale_image Upscale images to 4x resolution using AI models **Parameters:** - `image_path` (required): Path to image file (e.g., "flux_output_00001_.png") - `model`: Upscaling model ('ultrasharp' or 'animesharp', default: 'ultrasharp') - `scale_factor`: Additional scaling (0.5-2.0, default: 1.0) - `content_type`: Auto-select model ('general', 'anime', 'artwork', 'illustration') **Example:** ``` Upscale the image "flux_output_00001_.png" using the ultrasharp model ``` ### remove_background Remove background from images using RMBG-2.0 AI model **Parameters:** - `image_path` (required): Path to image file - `alpha_matting`: Use alpha matting for edges (default: true) - `output_format`: Output format 'png' or 'webp' (default: 'png') **Example:** ``` Remove the background from "flux_output_00001_.png" ``` ### check_models Verify available models in ComfyUI ### connect_comfyui / disconnect_comfyui Manually manage ComfyUI connection (usually auto-connects) ## System Information ### Optimized Setup - **PyTorch**: 2.5.1 with CUDA 12.1 (latest stable) - **Model**: FLUX schnell fp8 (4-step optimized) - **VRAM Usage**: ~10GB with fp8 quantization - **Container Size**: 10.9GB (optimized from 14.6GB) - **Build System**: Docker BuildKit with cache mounts - **Custom Nodes**: ComfyUI-Manager, KJNodes, RMBG ### Performance - **Generation Time**: ~2-4 seconds per image - **Batch Generation**: ~1.5 seconds per additional image - **Upscaling**: 1024x1024 → 4096x4096 in seconds - **Background Removal**: Near instant with RMBG-2.0 ## Troubleshooting ### Container not found If you get "container not found" errors: ```bash # Check container names docker ps --format "table {{.Names}}" # The correct container names are: # - mcp-comfyui-flux-comfyui-1 (ComfyUI) # - mcp-comfyui-flux-mcp-server-1 (MCP Server) ``` ### Connection refused If MCP can't connect to ComfyUI: ```bash # Check ComfyUI is healthy docker logs mcp-comfyui-flux-comfyui-1 --tail 50 # Check MCP server logs docker logs mcp-comfyui-flux-mcp-server-1 --tail 20 # Restart containers docker compose -p mcp-comfyui-flux restart ``` ### Out of memory If generation fails with OOM: - The system uses fp8 models which require ~10GB VRAM - Ensure WSL2 has enough memory allocated (20GB+ recommended) - Check `.wslconfig` in Windows user directory - Monitor usage: `docker exec mcp-comfyui-flux-comfyui-1 nvidia-smi` ### Port conflicts If port 8188 is in use: ```bash # Check what's using the port lsof -i :8188 # Linux/macOS netstat -ano | findstr :8188 # Windows # Change port in .env file PORT=8189 ``` ### WSL2 specific issues If experiencing crashes or slowdowns: - Avoid recursive operations on large directories - Check WSL2 memory allocation - Use BuildKit cache mounts (already configured) - Monitor with: `free -h` in WSL2 ## Testing ### Test MCP server directly: ```bash # Run example script docker exec mcp-comfyui-flux-mcp-server-1 node /app/examples/example.js # Test upscaling docker exec mcp-comfyui-flux-mcp-server-1 node /app/examples/example-upscale.js ``` ### Test from Claude Desktop: After configuration, in Claude: 1. Type: `/mcp` to see available servers 2. Ask: "Generate an image of a cute robot cat" 3. Check output in `./output/` directory ### Check system status: ```bash # View all logs docker compose -p mcp-comfyui-flux logs -f # Check resource usage docker stats --no-stream # Verify GPU is being used docker exec mcp-comfyui-flux-comfyui-1 python3.11 -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}')" ``` ## Advanced Usage ### Batch Generation Generate multiple variations efficiently: ``` Generate 4 images of "fantasy dragon, different poses" with batch_size=4 ``` ### Workflow Pipeline Combine tools for complex workflows: 1. Generate image: "portrait of a character" 2. Remove background from the generated image 3. Upscale the result to 4K ### Custom Seeds For reproducible results: ``` Generate "cyberpunk cat" with seed=42 ``` Same seed = same image every time ## File Locations - **Generated Images**: `./output/flux_output_*.png` - **Upscaled Images**: `./output/upscaled_*.png` - **Background Removed**: `./output/bg_removed_*.png` - **Models**: `./models/unet/`, `./models/clip/`, `./models/vae/` - **Logs**: `./install.log`, container logs via `docker logs` ## Updating To update to the latest version: ```bash # Pull latest changes git pull # Rebuild with optimizations ./build.sh --cleanup # Restart services docker compose -p mcp-comfyui-flux up -d ``` ## Support - **Issues**: Report at [GitHub Issues](https://github.com/yourusername/mcp-comfyui-flux/issues) - **Logs**: Always include output from `docker logs mcp-comfyui-flux-mcp-server-1 --tail 50` - **System Info**: Include output from `docker version` and `nvidia-smi` (if GPU)