ComfyUI MCP

English · Español

ComfyUI MCP — Generación de imágenes para agentes IA vía Model Context Protocol (MCP)

Conecta la generación de imágenes SDXL a cualquier agente IA en tu red.

Servidor MCP open source que expone inferencia de ComfyUI (SDXL / RTX 3060) a Claude Code, Cursor, Windsurf, Hermes Gateway y cualquier cliente compatible con Model Context Protocol. FastMCP HTTP/SSE + GPU Arbiter, cero dependencias en clientes, 100% en tu hardware.

Tags: mcp-server · comfyui · sdxl · image-generation · ai-agents · fastmcp · claude-code · cursor · hermes-gateway · gpu-arbiter · local-first · self-hosted

El agente pide una imagen con un preset y recibe la URL de descarga — la GPU trabaja en el server, el cliente no instala PyTorch.

💡 Por qué existe

Generar imágenes en entornos multi-agente requiere instalar bibliotecas pesadas de PyTorch, GPUs dedicadas y configuraciones complejas en cada máquina cliente. ComfyUI MCP resuelve esto actuando como un adaptador middleware HTTP/SSE desacoplado:

• 🚀 Cero Instalación Local: Cualquier cliente o gateway consumirá la generación de imágenes vía HTTP/SSE en puerto 8201 sin instalar PyTorch ni bajar modelos SDXL localmente.
• 🧠 GPU Arbiter Inteligente: Alterna automáticamente entre llama-server (LLMs) y ComfyUI en GPUs de 12GB (RTX 3060) sin colisiones de VRAM.
• 🎯 Presets Profesionales: Generación lista para producción con presets como producto (RealVisXL V4.0) o realista (Juggernaut XL).

🏗️ Arquitectura y Deslinde de Componentes

⚠️ IMPORTANTE: Entender los Límites del Sistema

comfyui-mcp es únicamente la capa de transporte e interfaz MCP. No incluye el motor de inferencia de ComfyUI ni los archivos de peso de modelos.

Para la guía de despliegue del servidor backend en el host Linux/Pop!_OS, consulta docs/SERVER_SETUP.md y docs/ARCHITECTURE.md.

 +-------------------------------------------------------+

| Clientes MCP (LAN) | | (Claude Code CLI / Cursor / Windsurf / Hermes Gateway)| +-------------------------------------------------------+ | | HTTP / SSE (Puerto 8201) v +-------------------------------------------------------+ | comfyui-mcp Server | | (FastMCP + Workflow JSON Builder) | +-------------------------------------------------------+ | | Loopback HTTP (Puerto 8188) v +-------------------------------------------------------+ | ComfyUI Backend Host | | (PyTorch + CUDA + SDXL Checkpoints + GPU Arbiter) | +-------------------------------------------------------+

📦 Instalación Rápida

Requisitos

• Python 3.11+
• uv ≥ 0.13.4 (recomendado) o pip ≥ 26.2.2: las versiones anteriores aún confían en la CA emSign comprometida (GHSA-6q48-6c7w-9gw2). pyproject.toml exige el mínimo de uv ([tool.uv] required-version).

Clonar e Instalar

git clone https://github.com/GermaniU/comfyui-mcp.git

cd comfyui-mcp

Crear entorno virtual e instalar

uv venv source .venv/bin/activate uv pip install -e .

⚙️ Configuración (Variables de Entorno)

Crea un archivo .env o exporta las siguientes variables:

Seguridad: sin MCP_AUTH_TOKEN, cualquier equipo de la LAN —o una página web abierta en un navegador de la LAN, con CORS *— puede generar imágenes y ocupar la GPU. Definir un token es lo recomendado salvo en redes totalmente confiables.

🛠️ Herramientas Expuestas (Tool Reference)

1. generate_image (txt2img)

Genera imágenes desde un prompt textual usando SDXL.

• Parámetros:
• prompt (*string*, requerido): Descripción de la imagen (en inglés funciona mejor).
• preset (*string*, opcional): producto, realista, rapido o anime. Default: "producto".
• aspect (*string*, opcional): 1:1, 4:5, 5:4, 9:16, 16:9, 3:2, 2:3 (~1MP). Default: "1:1".
• negative_prompt (*string*, opcional): Elementos a excluir. Default: negativo genérico de calidad.
• seed (*integer*, opcional): Semilla para reproducibilidad. Default: aleatoria.
• batch (*integer*, opcional): Imágenes por llamada (1-4). Default: 1.
• checkpoint, lora, lora_strength, steps, cfg (opcionales): Sobreescriben los valores del preset.
• filename_prefix (*string*, opcional): Prefijo del archivo de salida. Default: "mcp".
• detail_face (*bool*, opcional): Pasada de FaceDetailer (requiere Impact Pack). Default: false.
• preview (*bool*, opcional): Devuelve además una miniatura JPEG (~512px) para que el modelo vea el resultado. Solo para clientes con visión. Default: false.

2. img2img (Image-to-Image)

Varía una imagen ya generada (en output/ de ComfyUI) con un nivel de denoise.

• Parámetros:
• image_filename (*string*, requerido): Nombre del archivo generado (ej: mcp_00001_.png).
• prompt (*string*, opcional): Instrucción de transformación. Vacío = variación visual pura.
• denoise (*float*, opcional): 0.0 idéntica, 1.0 completamente nueva. Default: 0.55.
• preset (*string*, opcional): Default: "realista".
• negative_prompt, seed, checkpoint, lora, lora_strength, steps, cfg, filename_prefix, preview (opcionales).

3. generate_video (Wan 2.2)

Genera MP4 de 1-5 s. Sin imagen usa Wan 2.2 TI2V 5B (~720p, 24 fps, 30 pasos uni_pc/simple, CFG 5, shift 8); con image_filename recomienda Wan 2.2 A14B I2V GGUF (16 fps, 480×832 o 832×480). En benchmarks locales de 5 s/121 frames, el 5B fp8 tardó 1620.7–1903.6 s (~27–31.7 min) en dos escenas/orientaciones; A14B I2V, 489.2 s (~8.2 min) para 81 frames con una imagen de mapache. Son mediciones, no garantías para otros inputs ni para draft. Requiere modelos separados (ver SERVER_SETUP). No se ha probado aún esta integración MCP contra la GPU real.

• Parámetros:
• prompt (*string*, requerido): Escena y movimiento, preferentemente en inglés.
• aspect (*string*, opcional): A14B 16:9 (832×480) o 9:16 (480×832); 5B 16:9 (1280×704), 9:16 (704×1280) o 1:1 (960×960). Default "16:9"; A14B explícito rechaza 1:1 y auto elige 5B.
• seconds (*integer*, opcional): 1-5 (se recorta fuera del rango); A14B 16 fps + 1 frame (5 s = 81), 5B 24 fps + 1 (5 s = 121). Default 3.
• image_filename (*string*, opcional): Imagen generada a animar desde [output]; conviene igualar la orientación. auto elige A14B solo con imagen, parámetros compatibles y nodos/pesos disponibles en ComfyUI; de lo contrario usa 5B e indica el motivo. Sin imagen usa 5B.
• model (*string*, opcional): auto (default), a14b (requiere imagen) o 5b (conserva la ruta I2V previa y T2V). No cambia los argumentos anteriores.
• draft (*bool*, opcional): Solo 5B: mantiene la resolución ~720p y recorta a un máximo de 2 s (49 frames a 24 fps); no reduce resolución ni tiene tiempo medido. A14B rechaza draft=true.
• steps, cfg: A14B fija 4 y 1 con LoRA lightx2v; valores incompatibles con A14B explícito devuelven error, mientras auto elige 5B. 5B usa 30 y 5 por defecto; valores explícitos los sustituyen.
• negative_prompt, seed, filename_prefix (opcionales). Default de prefijo "mcp-video".
• preview (*bool*, opcional): Miniatura JPEG del primer frame.

Los timeouts se configuran al iniciar el servidor con las variables anteriores: cuentan desde el envío, incluyendo cola, carga y generación; no garantizan un tiempo de respuesta ni una cancelación efectiva. Al vencer se intenta retirar el prompt de la cola e interrumpir ComfyUI, pero el trabajo puede continuar y la interrupción de ComfyUI puede afectar otra ejecución concurrente. Ajusta los límites según carga real y timeout del cliente MCP. negative_prompt=null usa el negativo por defecto; "" lo desactiva.

4. list_models

Retorna la lista de checkpoints, LoRAs y presets disponibles en la instancia de ComfyUI.

5. comfy_health

Obtiene el estado de salud del backend: versión de ComfyUI, uso de VRAM de la GPU y tareas en cola.

6. comfy_view_url

Construye la URL LAN de descarga directa para un archivo generado previamente dado su filename y subfolder.

🎨 Matriz de Presets

🧭 ¿Y los otros servidores MCP de ComfyUI?

Hay tres familias, y resuelven problemas distintos. Este no compite con las otras dos: las complementa.

| Cliente | HT