pi_mcps/docs/wiki/pages/mcp-image-gen-ComfyUI-Setup.md

⚙️ ComfyUI Setup Guide (AMD ROCm)

This guide covers installing ComfyUI with FLUX.1-schnell on a Fedora Linux system with an AMD GPU.

Prerequisites

• AMD GPU with ROCm support (tested: RX 7900 XTX)
• Fedora Linux (tested: Fedora 43 / kernel 6.19)
• Python 3.11+
• ~15GB free disk space (model weights)
• HuggingFace account with FLUX license accepted

Step 1: Install ComfyUI

ComfyUI is not on PyPI — must be cloned from source:

cd ~
git clone https://github.com/comfyanonymous/ComfyUI
cd ComfyUI
python -m venv .venv
source .venv/bin/activate

# Install PyTorch ROCm build (CRITICAL for AMD GPUs)
pip install torch torchvision --index-url https://download.pytorch.org/whl/rocm6.2

# Install ComfyUI dependencies
pip install -r requirements.txt

Step 2: Download FLUX.1-schnell

FLUX.1-schnell is gated on HuggingFace — you must:

1. Create a HuggingFace account
2. Accept the FLUX.1-schnell license at https://huggingface.co/black-forest-labs/FLUX.1-schnell
3. Generate an access token at https://huggingface.co/settings/tokens

# Install huggingface_hub
pip install huggingface_hub

# Download model (requires HF token)
huggingface-cli download black-forest-labs/FLUX.1-schnell \
  flux1-schnell.safetensors \
  --local-dir ~/ComfyUI/models/checkpoints \
  --token YOUR_HF_TOKEN_HERE

Step 3: Download VAE and CLIP Models

FLUX.1-schnell also requires VAE and CLIP text encoders:

# VAE
huggingface-cli download black-forest-labs/FLUX.1-schnell \
  ae.safetensors \
  --local-dir ~/ComfyUI/models/vae

# CLIP models (T5 and CLIP-L)
huggingface-cli download comfyanonymous/flux_text_encoders \
  t5xxl_fp8_e4m3fn.safetensors clip_l.safetensors \
  --local-dir ~/ComfyUI/models/clip

Step 4: Install the systemd User Service (Recommended)

Installing ComfyUI as a systemd user service ensures it starts automatically on login and restarts on failure.

# Copy the bundled service file to the systemd user directory
mkdir -p ~/.config/systemd/user
cp ~/pi_mcps/mcp/mcp-image-gen/comfyui.service ~/.config/systemd/user/comfyui.service

# Reload systemd, enable + start the service
systemctl --user daemon-reload
systemctl --user enable --now comfyui

# Verify it is running
systemctl --user status comfyui

⚠️ HSA_OVERRIDE_GFX_VERSION=11.0.0 is already set in the service file — it is mandatory for RX 7900 XTX on ROCm. Without it, model loading fails silently.

Enable lingering (start ComfyUI even without a login session)

loginctl enable-linger $USER

This ensures the service starts at boot even before you log in — recommended for headless / homelab setups.

Managing the service

# Follow live logs
journalctl --user -u comfyui -f

# Restart after model changes
systemctl --user restart comfyui

# Stop temporarily
systemctl --user stop comfyui

# Disable autostart
systemctl --user disable comfyui

Step 5: Manual Start (without systemd)

If you prefer to start ComfyUI manually (e.g. for debugging):

cd ~/ComfyUI

# AMD GPU REQUIRES this environment variable
HSA_OVERRIDE_GFX_VERSION=11.0.0 \
  nohup .venv/bin/python main.py --listen --port 8188 > /tmp/comfyui.log 2>&1 &

echo "ComfyUI PID: $!"

Step 6: Verify ComfyUI is Running

curl http://localhost:8188/system_stats
# Should return JSON with GPU info

Step 7: Configure mcp-image-gen

cd /home/pplate/pi_mcps/mcp/mcp-image-gen

# Environment variables (set in .roo/mcp.json or shell):
# COMFYUI_URL=http://localhost:8188      — ComfyUI API endpoint
# IMAGE_OUTPUT_DIR=~/Pictures/mcp-generated — where generated images are saved
# COMFYUI_TIMEOUT=120                    — max wait time (seconds) per image
# COMFYUI_DIR=~/ComfyUI                  — path to ComfyUI install (used by auto-start)

Auto-start behaviour

mcp-image-gen includes a startup health check in its lifespan. Every time the MCP server starts it:

1. Pings http://localhost:8188/system_stats
2. If reachable — logs ComfyUI is already running ✓ and proceeds normally.
3. If not reachable — attempts to launch ComfyUI as a background subprocess from COMFYUI_DIR using .venv/bin/python main.py --listen --port 8188 with HSA_OVERRIDE_GFX_VERSION=11.0.0 injected automatically.
4. Polls up to 30 s for ComfyUI to become ready.

With the systemd service enabled, step 3 is never needed in practice — but the check acts as a safety net.

Performance

GPU	Model	Resolution	Steps	Time
AMD RX 7900 XTX	FLUX.1-schnell	1024×1024	4	~8s
AMD RX 7900 XTX	FLUX.1-schnell	1280×512	4	~7s

Architecture Overview

Boot
 └─ systemd --user (comfyui.service)
       └─ ComfyUI at localhost:8188

VS Code / Roo Code
 └─ mcp-image-gen MCP server (stdio)
       ├─ lifespan startup: ping localhost:8188
       │    └─ if down: subprocess.Popen ComfyUI, wait ≤30s
       └─ tools: generate_image, list_available_models, …

Troubleshooting

Problem	Solution
HTTP 401 downloading model	Accept FLUX license on HuggingFace first
GPU not detected	Ensure HSA_OVERRIDE_GFX_VERSION=11.0.0 is set
Connection refused from mcp-image-gen	Check systemctl --user status comfyui; or set COMFYUI_DIR so auto-start can locate the install
Slow generation (>60s)	ComfyUI may be running on CPU — check ROCm install and HSA_OVERRIDE_GFX_VERSION
Ollama image gen	As of April 2026: macOS-only, not available on Linux
Auto-start logs	journalctl --user -u comfyui -f or check mcp-image-gen server logs
Service not starting at boot	Run loginctl enable-linger $USER to enable session-less startup