ComfyUI MCP local : générer des images sur ton GPU

Pourquoi brancher ComfyUI à Claude Code

Tu travailles sur un projet qui demande des images : maquettes, illustrations, variations de style, assets de jeu. Le flux habituel ressemble à ça : tu quittes ton éditeur, tu ouvres un onglet Midjourney ou Stable Diffusion, tu copies-colles un prompt, tu attends, tu télécharges, tu retournes dans ton terminal. Vingt fois de suite.

Avec un MCP ComfyUI local, Claude Code devient la seule interface. Tu décris ce dont tu as besoin en langage naturel, le MCP traduit ça en workflow de génération, ComfyUI tourne en arrière-plan sur ton GPU, et l'image arrive dans ton dossier de projet. Tout ça sans quitter ta session de code.

Cet article te montre comment mettre ça en place de A à Z : comprendre ce qui se passe dans le modèle, installer ComfyUI avec Flux Schnell sur ton GPU, connecter le MCP à Claude Code, et gérer les erreurs courantes. Le tuto cible Linux/WSL2 avec un GPU NVIDIA, mais les concepts s'appliquent à tous les systèmes.

Comment marche un modèle de diffusion

Avant de lancer des commandes, un tour rapide sous le capot. Pas besoin de mathématiques, juste les concepts qui t'aideront à comprendre pourquoi certains paramètres existent et pourquoi certaines erreurs arrivent.

Le bruit comme point de départ

Un modèle de diffusion ne "dessine" pas une image. Il part d'une image de bruit pur (des pixels aléatoires, comme de la neige sur un vieux téléviseur) et il la débruite progressivement, étape par étape, jusqu'à obtenir quelque chose de cohérent. Le texte de ton prompt guide chaque étape de débruitage.

L'analogie la plus proche : imagine un sculpteur qui travaille sur un bloc de marbre recouvert d'un brouillard dense. Il ne voit pas encore la statue finale, mais à chaque coup de ciseau il révèle un peu plus de forme, en s'aidant d'une description écrite de ce qu'il cherche à obtenir.

L'espace latent : la carte compressée

Le U-Net : l'artiste qui débruite

Le sampler : le rythme du débruitage

Le VAE : le traducteur image/latent

Le ControlNet : le gabarit imposé

Pourquoi ComfyUI plutôt qu'AUTOMATIC1111

Il existe plusieurs interfaces pour lancer des modèles de diffusion localement. Les deux plus connues sont AUTOMATIC1111 (aussi appelé SD WebUI) et ComfyUI. Le choix dépend de ton usage.

ComfyUI s'impose pour deux raisons concrètes ici. D'abord, son architecture en graphe de noeuds correspond exactement à ce que fait un workflow de diffusion (chaque noeud = une opération, les liens = le flux de données). Ensuite, son API REST locale sur le port 8188 est ce que le MCP va appeler pour déclencher une génération.

Pré-requis matériel

Le modèle qui tourne influence directement la VRAM nécessaire. Voici un tableau réaliste basé sur les tailles officielles des fichiers de modèles :

Autres pré-requis :

• GPU NVIDIA avec pilotes récents (CUDA 12.6+ recommandé)
• Python 3.12 ou 3.13 (3.13 recommandé par la doc officielle ComfyUI)
• Git pour cloner le dépôt

Installation de ComfyUI et de Flux Schnell

git clone https://github.com/Comfy-Org/ComfyUI.git
cd ComfyUI

python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# Sur Windows : venv\Scripts\activate

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126

pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

pip install -r requirements.txt

# Installer huggingface-cli si absent
pip install huggingface_hub

# Télécharger le modèle fp8 directement dans le bon dossier
huggingface-cli download Comfy-Org/flux1-schnell flux1-schnell-fp8.safetensors \
  --local-dir ./models/checkpoints/

mkdir -p models/checkpoints
wget -O models/checkpoints/flux1-schnell-fp8.safetensors \
  https://huggingface.co/Comfy-Org/flux1-schnell/resolve/main/flux1-schnell-fp8.safetensors

python main.py

python main.py --lowvram

Brancher un MCP ComfyUI à Claude Code

Plusieurs projets MCP pour ComfyUI existent sur GitHub. Le plus léger pour notre usage est comfyui-mcp-server de joenorton, un serveur Python activement maintenu qui expose une API MCP et délègue la génération à ComfyUI via son API REST sur le port 8188.

Installation du serveur MCP

# Dans un dossier séparé (pas dans ComfyUI)
git clone https://github.com/joenorton/comfyui-mcp-server.git
cd comfyui-mcp-server

# Activer le même venv ou en créer un dédié
pip install -r requirements.txt

# Lancer le serveur MCP
python server.py

Le serveur MCP écoute sur http://127.0.0.1:9000/mcp. Il attend que ComfyUI tourne déjà sur le port 8188.

Configuration dans Claude Code

Crée ou modifie le fichier .mcp.json à la racine de ton projet :

{
  "mcpServers": {
    "comfyui": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:9000/mcp"
    }
  }
}

Ce que le MCP expose à Claude

Une fois connecté, Claude Code dispose des outils suivants :

• generate_image : génère une image depuis un prompt textuel
• list_models : liste les modèles disponibles dans ComfyUI
• get_queue_status : vérifie les jobs en attente ou en cours
• list_assets : parcourt les images déjà générées
• run_workflow : exécute un workflow JSON personnalisé

Alternative : wrapper TypeScript minimal

Si tu préfères une intégration plus directe sans serveur intermédiaire, voici un wrapper minimal en TypeScript qui POST directement sur l'API ComfyUI. Il utilise la même API McpServer + server.tool() que le tutoriel Créer un MCP en TypeScript, pour rester cohérent avec les autres exemples du site.

// comfyui-mcp-wrapper.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const COMFYUI_URL = "http://127.0.0.1:8188";

const server = new McpServer({
  name: "comfyui-local",
  version: "0.1.0",
});

server.tool(
  "generate_image",
  "Génère une image via ComfyUI local en POST sur /prompt",
  {
    prompt: z.string().describe("Description textuelle de l'image"),
    steps: z.number().default(4).describe("Nombre d'étapes de débruitage"),
  },
  async ({ prompt, steps }) => {
    const workflow = {
      "1": { inputs: { text: prompt, clip: ["2", 0] }, class_type: "CLIPTextEncode" },
      "2": { inputs: { ckpt_name: "flux1-schnell-fp8.safetensors" }, class_type: "CheckpointLoaderSimple" },
      "3": { inputs: { seed: Math.floor(Math.random() * 1e9), steps, cfg: 1.0, sampler_name: "euler", scheduler: "simple", denoise: 1.0, model: ["2", 0], positive: ["1", 0], negative: ["4", 0], latent_image: ["5", 0] }, class_type: "KSampler" },
      "4": { inputs: { text: "", clip: ["2", 1] }, class_type: "CLIPTextEncode" },
      "5": { inputs: { width: 1024, height: 1024, batch_size: 1 }, class_type: "EmptyLatentImage" },
      "6": { inputs: { samples: ["3", 0], vae: ["2", 2] }, class_type: "VAEDecode" },
      "7": { inputs: { filename_prefix: "claude_gen", images: ["6", 0] }, class_type: "SaveImage" },
    };

    const res = await fetch(`${COMFYUI_URL}/prompt`, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ prompt: workflow }),
    });

    const data = (await res.json()) as { prompt_id: string };
    return {
      content: [{ type: "text" as const, text: `Image en file. ID: ${data.prompt_id}` }],
    };
  }
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
}

main().catch((err) => {
  console.error("Erreur MCP:", err);
  process.exit(1);
});

Pour utiliser ce wrapper via stdio, la config .mcp.json devient :

{
  "mcpServers": {
    "comfyui": {
      "command": "npx",
      "args": ["ts-node", "comfyui-mcp-wrapper.ts"]
    }
  }
}

Premier prompt depuis Claude Code

Une fois les deux serveurs lancés (ComfyUI sur 8188, MCP sur 9000) et Claude Code redémarré pour charger la config MCP, tu peux tester directement dans ta session :

Génère une image d'un robot astronaute regardant la Terre depuis la Lune,
style illustration vectorielle, couleurs cyan et ambre, fond noir.
Taille 1024x1024, 4 étapes.

Claude Code appelle l'outil generate_image avec ces paramètres, le MCP transmet le workflow à ComfyUI, et la génération démarre. Sur un GPU de 8 Go avec Flux Schnell fp8 en 4 étapes, compte environ 10 à 30 secondes selon ta carte.

Le résultat atterrit dans le dossier ComfyUI/output/ avec un nom de fichier horodaté (ComfyUI_00001_.png ou le préfixe défini dans le workflow). Tu peux demander à Claude Code de lister les images générées avec list_assets, ou simplement ouvrir le dossier.

Troubleshooting

Les quatre erreurs les plus courantes quand on démarre avec ComfyUI sur GPU.

Prochaines étapes

Tu as ComfyUI qui tourne en local et Claude Code qui peut générer des images. La suite logique :

• Piloter un workflow JSON ComfyUI depuis Claude Code : aller plus loin avec les workflows personnalisés, les paramètres de sampling avancés et les techniques img2img.
• Panorama Claude Code + IA générative : situer ce setup local parmi les quatre patterns d'intégration, et savoir quand basculer vers le cloud.

Un comparatif détaillé local vs cloud (coût total, quand un GPU local devient rentable face aux APIs Replicate ou fal.ai) viendra compléter cette série.