mcp-comfyui-flux: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a fully containerized MCP (Model Context Protocol) server that integrates with ComfyUI to generate images using FLUX schnell fp8 models. The entire system runs in optimized Docker containers with BuildKit cache mounts, PyTorch 2.5.1, automatic setup, GPU acceleration, and Claude Desktop integration.

Quick Start for Development

# Build containers (with optional flags)
./build.sh                    # Build only
./build.sh --start           # Build and start
./build.sh --start --cleanup # Build, start, and cleanup old images

# Or use the one-command setup
./install.sh

# Access the development environment
docker exec -it mcp-comfyui-flux-mcp-server-1 bash
cd /app
claude  # Claude Code is pre-installed

# Or work directly with the code
docker exec -it mcp-comfyui-flux-mcp-server-1 claude --dir /app

MCP Server Usage

Available MCP Tools

1. generate_image

Generate high-quality images using FLUX schnell fp8 model.

Function Signature:

generate_image({
  prompt: string,           // Required: Description of image to generate
  negative_prompt?: string, // Optional: What to avoid (default: '')
  width?: number,          // Optional: Image width (default: 1024)
  height?: number,         // Optional: Image height (default: 1024)
  steps?: number,          // Optional: Generation steps (default: 4)
  cfg_scale?: number,      // Optional: Guidance scale (default: 1.0)
  seed?: number,           // Optional: Random seed (default: -1 for random)
  sampler_name?: string,   // Optional: Sampler method (default: 'euler')
  scheduler?: string,      // Optional: Scheduler type (default: 'simple')
  batch_size?: number      // Optional: Number of images to generate (default: 1, max: 8)
})

Optimized Defaults for FLUX schnell:

• steps: 4 - FLUX schnell is specifically designed for 4-step generation
• cfg_scale: 1.0 - Low guidance works best with schnell's distilled model
• scheduler: 'simple' - Optimal for schnell's architecture
• sampler_name: 'euler' - Most stable and predictable results
• batch_size: 1 - Can be increased up to 8 for multiple variations