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

---

💡 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 (recomendado) o pip

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:

Variable	Valor por Defecto	Descripción
COMFYUI_URL	http://127.0.0.1:8188	URL loopback donde escucha el motor de ComfyUI.
COMFYUI_PUBLIC_URL	http://<YOUR_SERVER_IP>:8188	Base URL pública/LAN para descarga de imágenes.
MCP_HOST	0.0.0.0	Host binding para el servidor MCP.
MCP_PORT	8201	Puerto HTTP/SSE del servidor MCP.
MCP_AUTH_TOKEN	(vacío = sin auth)	Si se define, exige header Authorization: Bearer <token> en cada request HTTP/SSE.
MCP_CORS_ORIGINS	*	Orígenes CORS permitidos, separados por coma. Solo afecta a clientes que corren en un navegador.

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 un clip corto MP4 (24fps) con Wan 2.2 TI2V 5B. Sin imagen es txt2video; con image_filename anima esa imagen como primer frame. Requiere los modelos de video (ver SERVER_SETUP). En la RTX 3060 tarda varios minutos por clip.

• Parámetros:
  • prompt (string, requerido): Escena y movimiento (de cámara, del sujeto), en inglés.
  • aspect (string, opcional): 16:9 (1280x704), 9:16 (704x1280) o 1:1 (960x960). Default: "16:9".
  • seconds (integer, opcional): Duración, 1-5. Default: 3.
  • image_filename (string, opcional): Imagen ya generada a animar (ej: mcp_00001_.png); conviene que su aspect coincida con el del video.
  • draft (bool, opcional): Borrador a ~480p (832x480, 480x832, 640x640), menos de la mitad de píxeles y bastante más rápido; para probar el prompt antes de la versión final. Default: false.
  • negative_prompt, seed, steps, cfg, filename_prefix (opcionales). Default de prefijo: "mcp-video".
  • preview (bool, opcional): Miniatura JPEG del primer frame. Default: false.

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

Preset	Checkpoint Asociado	Pasos	CFG	Caso de Uso
producto	RealVisXL_V4.0.safetensors	30	5.5	Fotografía comercial y de producto fotorrealista (Default).
realista	juggernautXL_ragnarokBy.safetensors	30	5.0	Fotorrealismo versátil (escenas, personas, ambientes).
rapido	juggernautXL_ragnarokBy.safetensors + LoRA SDXL-Lightning	6	1.5	Vista previa y borradores en ~5 segundos.
anime	animagine-xl-3.1.safetensors	28	7.0	Ilustración estilo anime (checkpoint no incluido en el server).

---

🧭 ¿Y los otros servidores MCP de ComfyUI?

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

	ComfyUI MCP (este)	Servidores de workflow graph	APIs cloud de imagen
Qué le pides	Un prompt + preset (producto, realista, rapido, anime)	Un grafo de nodos en JSON (lo diseñas tú)	Un prompt a un servicio remoto
Saber ComfyUI	No	Sí	No
Dónde corre	Tu GPU (RTX 3060)	Tu GPU	El servidor de un tercero
Coste por imagen	0 (tu electricidad)	0	Por imagen, según proveedor
Privacidad	El prompt no sale de tu red	Igual	Tu prompt sale a la nube
Comparte la GPU con el LLM	Sí (GPU Arbiter, 12 GB)	Depende	N/A
Cliente	HTTP/SSE en LAN + stdio — cero PyTorch en el cliente	Normalmente stdio local	HTTP

En una frase:

• Si necesitas control total del grafo de nodos → un servidor de workflow graph (p. ej. comfy-pilot).
• Si no tienes GPU y no te importa pagar por imagen → una API cloud (Flux, Nano Banana, GPT-image).
• Si tienes la GPU y quieres generar sin aprender ComfyUI, compartiendo la tarjeta con tu LLM → este.

---

🔗 Integración con Clientes MCP

Configuración para Claude Code CLI (~/.claude.json)

{
  "mcpServers": {
    "comfyui": {
      "url": "http://<YOUR_SERVER_IP>:8201/mcp"
    }
  }
}

Configuración para Hermes Gateway (~/.hermes/config.yaml)

mcp_servers:
  comfyui:
    url: "http://<YOUR_SERVER_IP>:8201/mcp"
    transport: "http"

Configuración para Cursor / Windsurf / Claude Desktop

Añade un servidor MCP de tipo SSE / HTTP con la URL http://<LAN_IP>:8201/mcp.

---

📋 Componentes Faltantes y Roadmap (Server Gaps)

Dado que este repo representa la capa MCP, los siguientes elementos están fuera de este repositorio y deben configurarse en el servidor host:

1. Servidor Backend ComfyUI: Requiere instalación independiente de Python + PyTorch CUDA.
2. Descarga de Checkpoints: Los modelos SDXL deben descargarse manualmente en el directorio models/checkpoints/ del servidor ComfyUI.
3. GPU Arbiter Script: El script gpu-broker.sh y las reglas /etc/sudoers.d/gpu-arbiter deben residir en la máquina Linux con la GPU.
4. Futuras Mejoras del MCP:
   • Soporte para inyección de workflows JSON personalizados dinámicos.
   • Cancelación y limpieza de colas de procesamiento vía tool MCP.
   • Conexión por WebSocket para reporte de progreso en tiempo real.

---

🧪 Pruebas Unitarias

uv run --with pytest --with pytest-asyncio pytest

---

📄 Licencia

Este proyecto está bajo la Licencia MIT. Consulta el archivo LICENSE para más detalles.