comfyui-mcp

Servidor MCP para ComfyUI. Genera imágenes a partir de prompts en lenguaje natural utilizando cualquier cliente compatible con MCP.

Parte de la Serie de Servidores MCP.

Estado

v0.2: herramientas principales más escalado, proxy de imágenes y soporte para URL pública. Herramientas: generate_image, generate_variations, generate_with_workflow, refine_image, upscale_image, list_models, list_workflows, upload_image. Consulta la hoja de ruta para ver qué sigue.

Instalación

npx (no requiere instalación)

npx @miller-joe/comfyui-mcp --comfyui-url http://your-comfyui-host:8188

npm

npm install -g @miller-joe/comfyui-mcp
comfyui-mcp --comfyui-url http://your-comfyui-host:8188

Docker

docker run -p 9100:9100 \
  -e COMFYUI_URL=http://your-comfyui-host:8188 \
  ghcr.io/miller-joe/comfyui-mcp:latest

Conectar un cliente MCP

Ejemplo: Claude Code:

claude mcp add --transport http comfyui http://localhost:9100/mcp

O registra el endpoint HTTP transmitible con una pasarela MCP (por ejemplo, MetaMCP) para agregarlo con otros servidores.

Configuración

Todas las opciones se pueden establecer mediante flags de CLI o variables de entorno:

URL de imágenes devueltas a los clientes

Las herramientas de generación devuelven URL de imágenes como <comfyui-public-url>/view?filename=…. Si no se establece --comfyui-public-url, las URL utilizan el valor interno de --comfyui-url.

El servidor también expone un endpoint proxy: GET /images/<filename>?subfolder=&type=output transmite los bytes de la imagen a través del servidor MCP, lo cual es útil cuando los clientes pueden acceder al servidor MCP pero no directamente a ComfyUI.

El checkpoint predeterminado debe coincidir con un archivo instalado en tu directorio models/checkpoints/ de ComfyUI. Puedes sobrescribirlo mediante COMFYUI_DEFAULT_CKPT o pasar checkpoint como argumento de la herramienta.

Herramientas

generate_image

Genera una imagen a partir de un prompt de texto utilizando el flujo de trabajo txt2img predeterminado de ComfyUI.

Parámetros: prompt (obligatorio), negative_prompt, width, height, steps, cfg, seed, checkpoint.

generate_variations

Genera múltiples variaciones del mismo prompt variando la semilla. Devuelve todas las imágenes a la vez.

Parámetros: prompt (obligatorio), count (2–16, predeterminado 4), además de los mismos parámetros de generación que generate_image, con base_seed en lugar de seed.

generate_with_workflow

Envía un JSON de flujo de trabajo de ComfyUI arbitrario (grafo de nodos completo) y devuelve las URL de las imágenes resultantes. Úsalo para flujos de trabajo personalizados: ControlNet, escalado o cualquier cosa exportada desde Save (API Format) de ComfyUI.

Parámetro: workflow (objeto): el grafo de nodos completo.

refine_image

Ejecuta img2img en una imagen de origen: obtiene una URL de origen, la sube a ComfyUI y ejecuta una pasada de eliminación de ruido guiada por un nuevo prompt. Un denoise más bajo preserva más el original; uno más alto le da al prompt más libertad.

Parámetros: prompt, source_image_url (obligatorio), denoise (0–1, predeterminado 0.5), además de los parámetros de generación estándar.

list_models

Enumera los checkpoints, LoRAs, samplers o schedulers disponibles en la instancia de ComfyUI.

Parámetro: kind: uno de checkpoints (predeterminado), loras, samplers, schedulers.

list_workflows

Enumera las plantillas de flujo de trabajo integradas que vienen con este servidor (actualmente txt2img, img2img).

upload_image

Sube una imagen de referencia a ComfyUI para usarla en flujos de trabajo img2img, ControlNet o IP-Adapter.

Parámetros: source_url o image_base64 (uno obligatorio), filename (opcional), overwrite (predeterminado false).

Devuelve: el nombre de archivo almacenado, que se puede usar como entrada image en nodos de flujo de trabajo como LoadImage.

generate_with_controlnet

Genera una imagen condicionada por una imagen preprocesada de ControlNet (esqueleto de pose, mapa de profundidad, bordes canny, mapa de normales, etc.) más un prompt de texto.

Parámetros: prompt, control_image_url (la imagen de condicionamiento preprocesada; esta herramienta no ejecuta preprocesadores), controlnet_model (nombre de archivo de models/controlnet/), strength (0–2, predeterminado 1), start_percent / end_percent (0–1, cuando CN está activo durante el muestreo), además de los parámetros de generación estándar.

Requiere un modelo ControlNet instalado en tu directorio models/controlnet/ de ComfyUI.

generate_with_ip_adapter

Genera una imagen usando una imagen de referencia como guía visual/estilo/sujeto a través de IP-Adapter.

Parámetros: prompt, reference_image_url, preset (ej. "STANDARD (medium strength)", "PLUS FACE (portraits)", "VIT-G (medium strength)"), weight (0–3, predeterminado 1), start_at / end_at (0–1), además de los parámetros de generación estándar.

Requiere el paquete de nodos personalizados ComfyUI-IPAdapter-plus además de los pesos de IPAdapter y los modelos CLIP Vision que coincidan con el preset.

Registro de plantillas de flujo de trabajo

Guarda JSON de flujos de trabajo complejos una vez y ejecútalos por nombre más tarde. Las plantillas se almacenan en el disco bajo --templates-dir (por defecto ~/.config/comfyui-mcp/templates/<name>.json) para que sobrevivan a los reinicios y sean portátiles entre clientes MCP.

Los nombres de las plantillas deben comenzar con caracteres alfanuméricos; a-z, A-Z, 0-9, -, _; máximo 64 caracteres.

Formato de retorno

Todas las herramientas de generación devuelven URL de imágenes servidas directamente por la instancia de ComfyUI (http://<comfyui>/view?filename=…). Estas URL se pueden pasar directamente a cualquier cliente que acepte URL de imágenes.

Arquitectura

┌────────────────┐     ┌──────────────────┐     ┌──────────────┐
│  MCP client    │────▶│  comfyui-mcp     │────▶│  ComfyUI     │
│  (Claude, etc.)│◀────│  (this server)   │◀────│  instance    │
└────────────────┘     └──────────────────┘     └──────────────┘
     streamable HTTP        HTTP REST + poll

El servidor no tiene estado. Una única solicitud MCP → enviar flujo de trabajo a ComfyUI → sondear /history/{id} hasta completar → devolver URL de imágenes.

Desarrollo

git clone https://github.com/miller-joe/comfyui-mcp
cd comfyui-mcp
npm install
npm run dev       # hot-reload via tsx watch
npm run build     # compile TS to dist/
npm run typecheck # strict type checking

Requiere Node 20+.

Hoja de ruta

• [x] generate_image: texto a imagen con flujo de trabajo predeterminado

• [x] generate_with_workflow: enviar flujos de trabajo arbitrarios

• [x] list_models / list_workflows

• [x] upload_image: imágenes de referencia para img2img / ControlNet / IP-Adapter

• [x] generate_variations: variaciones por lotes de un prompt

• [x] refine_image: refinamiento img2img desde una URL de origen

• [x] upscale_image: escalado de modelo estilo ESRGAN/SwinIR

• [x] Endpoint proxy de imagen (/images/<filename>) para clientes que no pueden acceder a ComfyUI

• [x] URL pública configurable para URL de imágenes externamente correctas

• [x] Registro de plantillas de flujo de trabajo: save_workflow_template, list_workflow_templates, get_workflow_template, delete_workflow_template, run_workflow_template

• [x] Ayudante de flujo de trabajo ControlNet: generate_with_controlnet (requiere modelos ControlNet en el lado de ComfyUI)

• [x] Ayudante de flujo de trabajo IP-Adapter: generate_with_ip_adapter (requiere el paquete ComfyUI-IPAdapter-plus)

• [ ] Eventos de progreso de WebSocket para generaciones de larga duración

Licencia

MIT © Joe Miller

Soporte

Si esta herramienta te ahorra tiempo, considera apoyar el desarrollo:

Cada contribución financia el mantenimiento, la documentación y el próximo lanzamiento de la Serie de Servidores MCP.