---
layout: modern
title: Documentation
---
<div class="doc-layout">
<aside class="doc-sidebar">
<div class="sidebar-section">
<div class="sidebar-title">Installation</div>
<nav class="sidebar-nav">
<a href="#prerequisites" class="sidebar-link">Prerequisites</a>
<a href="#quick-install" class="sidebar-link">Quick Install</a>
<a href="#manual-setup" class="sidebar-link">Manual Setup</a>
<a href="#configuration" class="sidebar-link">Configuration</a>
</nav>
</div>
<div class="sidebar-section">
<div class="sidebar-title">Docker Setup</div>
<nav class="sidebar-nav">
<a href="#containers" class="sidebar-link">Containers</a>
<a href="#networking" class="sidebar-link">Networking</a>
<a href="#volumes" class="sidebar-link">Volumes</a>
<a href="#environment" class="sidebar-link">Environment</a>
</nav>
</div>
<div class="sidebar-section">
<div class="sidebar-title">Troubleshooting</div>
<nav class="sidebar-nav">
<a href="#common-issues" class="sidebar-link">Common Issues</a>
<a href="#gpu-setup" class="sidebar-link">GPU Setup</a>
<a href="#memory-issues" class="sidebar-link">Memory Issues</a>
<a href="#debugging" class="sidebar-link">Debugging</a>
</nav>
</div>
</aside>
<div class="doc-content">
<h1>Complete Documentation</h1>
<p class="hero-subtitle">Everything you need to know about MCP-ComfyUI-FLUX, from installation to advanced configuration.</p>
<h2 id="prerequisites">Prerequisites</h2>
<div class="features-grid">
<div class="feature-card">
<div class="feature-icon">💻</div>
<h3 class="feature-title">System Requirements</h3>
<ul>
<li><strong>GPU:</strong> NVIDIA with 12GB+ VRAM</li>
<li><strong>RAM:</strong> 20GB+ system memory</li>
<li><strong>Storage:</strong> 50GB+ free space</li>
<li><strong>OS:</strong> Windows (WSL2), Linux, macOS</li>
</ul>
</div>
<div class="feature-card">
<div class="feature-icon">🔧</div>
<h3 class="feature-title">Software Requirements</h3>
<ul>
<li>Docker Desktop (latest)</li>
<li>NVIDIA Drivers (525+)</li>
<li>NVIDIA Container Toolkit</li>
<li>Git</li>
</ul>
</div>
<div class="feature-card">
<div class="feature-icon">🤖</div>
<h3 class="feature-title">Optional Software</h3>
<ul>
<li>Claude Desktop or Claude Code</li>
<li>Hugging Face account (for models)</li>
<li>WSL2 (Windows users)</li>
<li>CUDA Toolkit (advanced users)</li>
</ul>
</div>
</div>
<h2 id="quick-install">Quick Installation</h2>
<div class="api-endpoint">
<div class="api-header">
<span class="api-method">BASH</span>
<span class="api-path">One-Command Installation</span>
</div>
<div class="api-description">
<p>The fastest way to get started - handles everything automatically:</p>
</div>
<div class="code-content">
<pre><code class="language-bash"># Clone and install in one go
git clone https://github.com/dhofheinz/mcp-comfyui-flux.git && \
cd mcp-comfyui-flux && \
./install.sh</code></pre>
</div>
</div>
<div class="stats" style="margin: 2rem 0;">
<div class="stats-container">
<div class="stat-item">
<div class="stat-value">✅</div>
<div class="stat-label">Auto Downloads Models</div>
</div>
<div class="stat-item">
<div class="stat-value">✅</div>
<div class="stat-label">Builds Containers</div>
</div>
<div class="stat-item">
<div class="stat-value">✅</div>
<div class="stat-label">Configures Claude</div>
</div>
<div class="stat-item">
<div class="stat-value">✅</div>
<div class="stat-label">Starts Services</div>
</div>
</div>
</div>
<h2 id="manual-setup">Manual Setup</h2>
<h3>Step 1: WSL2 Configuration (Windows Only)</h3>
<div class="code-content">
<pre><code class="language-ini"># Create ~/.wslconfig
[wsl2]
memory=20GB
processors=8
localhostForwarding=true
nestedVirtualization=true
[experimental]
autoMemoryReclaim=gradual
sparseVhd=true</code></pre>
</div>
<p>After creating the config file, restart WSL:</p>
<div class="code-content">
<pre><code class="language-bash">wsl --shutdown
# WSL will restart automatically on next use</code></pre>
</div>
<h3>Step 2: Download Models</h3>
<div class="code-content">
<pre><code class="language-bash"># Download FLUX schnell fp8 model (11GB)
./scripts/download-models.sh
# Optional: Download upscaling models (128MB)
./scripts/download-upscale-models.sh
# Verify downloads
ls -lah models/unet/
ls -lah models/clip/</code></pre>
</div>
<h3>Step 3: Build and Start Containers</h3>
<div class="code-content">
<pre><code class="language-bash"># Build with optimizations
./build.sh --start
# Or manually with docker-compose
docker-compose -p mcp-comfyui-flux build
docker-compose -p mcp-comfyui-flux up -d
# Verify containers are running
docker ps | grep mcp-comfyui</code></pre>
</div>
<h2 id="configuration">Claude Desktop Configuration</h2>
<div class="feature-card">
<h3>Windows Configuration Path</h3>
<p><code>%APPDATA%\Claude\claude_desktop_config.json</code></p>
<div class="code-content">
<pre><code class="language-json">{
"mcpServers": {
"mcp-comfyui-flux": {
"command": "docker",
"args": [
"exec",
"-i",
"mcp-comfyui-flux-mcp-server-1",
"node",
"/app/dist/index.js"
],
"env": {}
}
}
}</code></pre>
</div>
</div>
<div class="feature-card">
<h3>macOS/Linux Configuration Path</h3>
<p><code>~/.config/Claude/claude_desktop_config.json</code></p>
<p>Use the same JSON configuration as above.</p>
</div>
<h2 id="containers">Docker Containers</h2>
<div class="api-endpoint">
<div class="api-header">
<span class="api-method">DOCKER</span>
<span class="api-path">Container Architecture</span>
</div>
<div class="api-parameters">
<div class="api-param">
<span class="param-name">mcp-comfyui-flux-comfyui-1</span>
<span class="param-type">ComfyUI</span>
<span class="param-desc">Main AI generation engine with FLUX models</span>
</div>
<div class="api-param">
<span class="param-name">mcp-comfyui-flux-mcp-server-1</span>
<span class="param-type">MCP Server</span>
<span class="param-desc">Bridge between Claude and ComfyUI</span>
</div>
</div>
</div>
<h3>Container Management Commands</h3>
<div class="code-tabs">
<button class="code-tab active" data-tab="start">Start/Stop</button>
<button class="code-tab" data-tab="logs">View Logs</button>
<button class="code-tab" data-tab="access">Access Containers</button>
</div>
<div class="code-content" id="start-content">
<pre><code class="language-bash"># Start containers
docker-compose -p mcp-comfyui-flux up -d
# Stop containers
docker-compose -p mcp-comfyui-flux down
# Restart containers
docker-compose -p mcp-comfyui-flux restart
# Rebuild and start
docker-compose -p mcp-comfyui-flux up -d --build</code></pre>
</div>
<div class="code-content" id="logs-content" style="display: none;">
<pre><code class="language-bash"># View all logs
docker-compose -p mcp-comfyui-flux logs -f
# View ComfyUI logs
docker logs mcp-comfyui-flux-comfyui-1 -f
# View MCP server logs
docker logs mcp-comfyui-flux-mcp-server-1 -f
# Last 100 lines
docker logs mcp-comfyui-flux-mcp-server-1 --tail 100</code></pre>
</div>
<div class="code-content" id="access-content" style="display: none;">
<pre><code class="language-bash"># Access ComfyUI container
docker exec -it mcp-comfyui-flux-comfyui-1 bash
# Access MCP server container
docker exec -it mcp-comfyui-flux-mcp-server-1 sh
# Run commands directly
docker exec mcp-comfyui-flux-comfyui-1 nvidia-smi
docker exec mcp-comfyui-flux-mcp-server-1 npm test</code></pre>
</div>
<h2 id="networking">Network Configuration</h2>
<div class="feature-card">
<h3>Docker Network</h3>
<ul>
<li><strong>Network Name:</strong> mcp-network</li>
<li><strong>Type:</strong> Bridge network</li>
<li><strong>Internal Access:</strong> comfyui:8188</li>
<li><strong>External Access:</strong> localhost:8188</li>
</ul>
</div>
<h2 id="volumes">Volume Mounts</h2>
<div class="code-content">
<pre><code class="language-yaml">volumes:
- ./models:/app/ComfyUI/models # AI models
- ./output:/app/ComfyUI/output # Generated images
- ./input:/app/ComfyUI/input # Input images
- ./custom_nodes:/app/ComfyUI/custom_nodes # Extensions</code></pre>
</div>
<h2 id="environment">Environment Variables</h2>
<div class="code-content">
<pre><code class="language-bash"># ComfyUI settings
COMFYUI_HOST=comfyui
COMFYUI_PORT=8188
# GPU settings
PYTORCH_CUDA_ALLOC_CONF=max_split_size_mb:512
MODEL_PRECISION=fp16
# Memory settings
DOCKER_SHM_SIZE=16g</code></pre>
</div>
<h2 id="common-issues">Common Issues & Solutions</h2>
<div class="features-grid">
<div class="feature-card">
<div class="feature-icon">⚠️</div>
<h3 class="feature-title">Container Won't Start</h3>
<div class="code-content">
<pre><code class="language-bash"># Check Docker status
docker info
# Clean restart
docker-compose -p mcp-comfyui-flux down
docker system prune -f
docker-compose -p mcp-comfyui-flux up -d</code></pre>
</div>
</div>
<div class="feature-card">
<div class="feature-icon">🔌</div>
<h3 class="feature-title">Claude Can't Connect</h3>
<ol>
<li>Verify containers are running</li>
<li>Check config file location</li>
<li>Restart Claude Desktop completely</li>
<li>Test with <code>/mcp</code> command</li>
</ol>
</div>
<div class="feature-card">
<div class="feature-icon">📦</div>
<h3 class="feature-title">Model Download Failed</h3>
<div class="code-content">
<pre><code class="language-bash"># Manual download with HF token
export HF_TOKEN="your_token"
./scripts/download-models.sh
# Verify model files
ls -la models/unet/*.safetensors</code></pre>
</div>
</div>
</div>
<h2 id="gpu-setup">GPU Setup & Verification</h2>
<div class="code-content">
<pre><code class="language-bash"># Check GPU in container
docker exec mcp-comfyui-flux-comfyui-1 nvidia-smi
# Verify CUDA
docker exec mcp-comfyui-flux-comfyui-1 python -c \
"import torch; print(f'CUDA available: {torch.cuda.is_available()}')"
# Check VRAM usage
watch -n 1 nvidia-smi</code></pre>
</div>
<h2 id="memory-issues">Memory Optimization</h2>
<div class="api-endpoint">
<div class="api-header">
<span class="api-method">CONFIG</span>
<span class="api-path">Memory Management Tips</span>
</div>
<div class="api-description">
<p>If you encounter out-of-memory errors:</p>
<ul>
<li>Reduce image dimensions (try 768x768 instead of 1024x1024)</li>
<li>Lower batch_size to 1</li>
<li>Ensure you're using fp8 models (not fp16)</li>
<li>Increase WSL2 memory allocation</li>
<li>Close other GPU-intensive applications</li>
</ul>
</div>
</div>
<h2 id="debugging">Debugging Tools</h2>
<div class="code-content">
<pre><code class="language-bash"># Run health check
./scripts/health-check.sh
# Test image generation
docker exec mcp-comfyui-flux-mcp-server-1 \
node examples/example.js
# Enable debug logging
docker exec mcp-comfyui-flux-mcp-server-1 \
DEBUG=mcp:* node dist/index.js
# Check model loading
docker exec mcp-comfyui-flux-comfyui-1 \
ls -la /app/ComfyUI/models/</code></pre>
</div>
<div class="hero-content" style="margin-top: 3rem; text-align: center;">
<h2 class="gradient-text">Ready to Generate?</h2>
<p class="hero-subtitle">You're all set up! Start creating amazing images.</p>
<div class="hero-buttons">
<a href="{{ site.baseurl }}/quickstart" class="btn btn-primary">
<i class="fas fa-rocket"></i> Quick Start Guide
</a>
<a href="{{ site.baseurl }}/examples" class="btn btn-secondary">
<i class="fas fa-flask"></i> View Examples
</a>
</div>
</div>
</div>
</div>
<script>
// Tab switching
document.querySelectorAll('.code-tab').forEach(tab => {
tab.addEventListener('click', () => {
const tabGroup = tab.parentElement;
tabGroup.querySelectorAll('.code-tab').forEach(t => t.classList.remove('active'));
tab.classList.add('active');
const contentId = tab.dataset.tab + '-content';
tabGroup.parentElement.querySelectorAll('.code-content').forEach(c => {
if (c.id && c.id.includes('-content')) {
c.style.display = 'none';
}
});
const content = document.getElementById(contentId);
if (content) content.style.display = 'block';
});
});
// Sidebar navigation
const sections = document.querySelectorAll('h2[id], h3[id]');
const navLinks = document.querySelectorAll('.sidebar-link');
window.addEventListener('scroll', () => {
let current = '';
sections.forEach(section => {
const sectionTop = section.offsetTop;
if (pageYOffset >= sectionTop - 100) {
current = section.getAttribute('id');
}
});
navLinks.forEach(link => {
link.classList.remove('active');
if (link.getAttribute('href') === `#${current}`) {
link.classList.add('active');
}
});
});
</script>
