comfyui-local-mcp

Controla tu ComfyUI local desde clientes MCP (Hermes, Claude Code, Cursor, cualquier agente MCP) — con flujos de trabajo FLUX.2 Klein de texto a imagen listos para usar, optimizados para Apple Silicon (MLX + MPS).

Construido y probado en: Mac mini M4 · 24 GB de memoria unificada · macOS 26 · ComfyUI 0.33 · mflux 0.19

Características

• 🖼️ generate_image — texto a imagen con descubrimiento automático de modelos:

  • mflux:<nombre> — FLUX.2 Klein 4B / 9B, MLX de 4 bits (rápido, bajo consumo de memoria)

  • bf16 — bf16 nativo de ComfyUI (MPS, mejor calidad)

  • auto — selecciona automáticamente el mejor modelo (preferencia por 9B)

• 📦 list_models — lista los modelos instalados (escanea automáticamente models/mflux/, añade modelos sin cambios de código)

• 🗂️ list_outputs — imágenes generadas recientemente

• 🩺 system_status — diagnóstico en una sola llamada (servicio ComfyUI, modelos, disco)

Related MCP server: comfyui-mcp

Inicio rápido

# 1. Install the server files into your ComfyUI + register the hermes MCP
./install.sh                # optional; also fine to just copy files

# 2. Register the MCP server manually (or via install.sh) — e.g. in ~/.hermes/config.yaml:
#   mcp_servers:
#     comfyui-local:
#       command: /path/to/python-with-mcp
#       args: [/path/to/comfyui-local-mcp/mcp_comfyui_server.py]
#       enabled: true

# 3. Test the server (stdio MCP handshake)
python mcp_comfyui_server.py

# 4. Ask your agent: "generate an image of ..." or "check my ComfyUI status"

Requisitos

• macOS con Apple Silicon (MLX / Metal)

• ComfyUI ejecutándose localmente (por defecto 127.0.0.1:8188)

• Entorno Python con el paquete mcp (el servidor solo necesita la biblioteca estándar + mcp)

• Opcional: mflux + nodo personalizado ComfyUI-mflux-AnyModel para la ruta MLX

• Opcional: pesos FLUX.2 Klein bf16 + codificador de texto Qwen3-4B para la ruta bf16

Configuración de modelos (Apple Silicon, compatible con 24 GB)

Descarga los modelos MLX de mflux usando la caché de HF y crea enlaces simbólicos en models/mflux/ (consulta Caché de HF / enlaces simbólicos) — el servidor los descubre automáticamente.

Notas sobre Apple Silicon

• Los pesos fp8 no funcionan en MPS — conviértelos primero a bf16 (una des-cuantización del lado de la CPU). flux-2-klein-4b-bf16.safetensors es una conversión a bf16 del checkpoint fp8 oficial.

• Las descargas de HF pueden bloquearse en algunas redes — export HF_HUB_DISABLE_XET=1 lo soluciona.

• Rendimiento (GPU M4 de 10 núcleos, 1024×1024): 4B-4bit ~12,7 s/paso (pico ~11 GB), bf16 ~12,1 s/paso (pico ~15 GB).

Caché de HF y enlaces simbólicos

snapshot_download de HuggingFace almacena los datos reales en ~/.cache/huggingface/hub/models--<org>--<name>/blobs/ y expone enlaces simbólicos bajo snapshots/<rev>/. Este proyecto mantiene enlaces simbólicos en models/mflux/<Nombre-del-Modelo>/ que apuntan a esas instantáneas — cero uso duplicado de disco, y list_models los detecta automáticamente.

Solución de problemas

./check_system.sh        # one-shot diagnosis
tail -50 ~/comfyui_run.log

• ¿ComfyUI no responde? Asegúrate de que se ejecute en 127.0.0.1:8188 (mata primero las instancias obsoletas).

• ¿Falta un modelo en list_models? Crea un enlace simbólico (o cópialo) en models/mflux/ con un subdirectorio transformer/.

• ¿MCP no visible en el agente? Reinicia la sesión del agente después de editar config.yaml.

Licencia

MIT