comfyui-mcp
by GermaniU
README.md
<p align="center">
<img src="docs/assets/og-image.png" alt="ComfyUI MCP — Generación de imágenes para agentes IA vía Model Context Protocol" width="720">
</p>
[English](README.en.md) · **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](https://modelcontextprotocol.io). FastMCP HTTP/SSE + GPU Arbiter, **cero dependencias en clientes, 100% en tu hardware**.
[](LICENSE)
[](https://modelcontextprotocol.io)
[](pyproject.toml)
[](https://github.com/GermaniU/comfyui-mcp/actions/workflows/ci.yml)
[](https://github.com/jlowin/fastmcp)
[](CONTRIBUTING.md)
[](https://mcprush.com/to/comfyui-mcp?ref=badge)
**Tags:** `mcp-server` · `comfyui` · `sdxl` · `image-generation` · `ai-agents` · `fastmcp` · `claude-code` · `cursor` · `hermes-gateway` · `gpu-arbiter` · `local-first` · `self-hosted`
<p align="center">
<img src="docs/assets/demo.gif" alt="El agente genera una imagen real vía MCP en la RTX 3060" width="780">
</p>
<p align="center"><sub>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.</sub></p>
---
## 💡 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](docs/SERVER_SETUP.md) y [docs/ARCHITECTURE.md](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
```bash
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. |
| `VIDEO_TIMEOUT_SECONDS` | `4200` | Espera máxima 5B tras enviar el prompt (incluye cola y carga fría). |
| `A14B_TIMEOUT_SECONDS` | `2700` | Espera máxima A14B tras enviar el prompt (incluye cola y carga fría). |
> **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](docs/SERVER_SETUP.md#-step-2b-modelos-de-video-wan-22)). 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
| 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`)
```json
{
"mcpServers": {
"comfyui": {
"url": "http://<YOUR_SERVER_IP>:8201/mcp"
}
}
}
```
### Configuración para Hermes Gateway (`~/.hermes/config.yaml`)
```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
```bash
uv run --with pytest --with pytest-asyncio pytest
```
---
## 📄 Licencia
Este código MCP está bajo la Licencia MIT ([LICENSE](LICENSE)); **no** licencia los modelos ni los distribuye. Los repositorios originales de [Wan 2.2 TI2V-5B](https://huggingface.co/Wan-AI/Wan2.2-TI2V-5B) y [Wan 2.2 I2V-A14B](https://huggingface.co/Wan-AI/Wan2.2-I2V-A14B) declaran Apache 2.0 para sus modelos. Los empaquetados ComfyUI, GGUF y LoRA de terceros pueden tener términos propios: verifica las licencias de cada distribución antes de descargarlos, redistribuirlos o usarlos comercialmente. Requisitos y nombres de archivos en [SERVER_SETUP](docs/SERVER_SETUP.md#-step-2b-modelos-de-video-wan-22).