comfyui-local-mcp

Управляйте локальной ComfyUI из MCP-клиентов (Hermes, Claude Code, Cursor, любой MCP-агент) — с готовыми FLUX.2 Klein пайплайнами text-to-image, оптимизированными для Apple Silicon (MLX + MPS).

Собрано и протестировано на: Mac mini M4 · 24 ГБ унифицированной памяти · macOS 26 · ComfyUI 0.33 · mflux 0.19

Возможности

• 🖼️ generate_image — text-to-image с автоматическим поиском модели:

  • mflux:<name> — FLUX.2 Klein 4B / 9B, 4-бит MLX (быстро, мало памяти)

  • bf16 — родной bf16 ComfyUI (MPS, наилучшее качество)

  • auto — автоматически выбирает лучшую модель (предпочтительно 9B)

• 📦 list_models — список установленных моделей (автосканирование models/mflux/, добавление моделей без изменения кода)

• 🗂️ list_outputs — недавно сгенерированные изображения

• 🩺 system_status — диагностика одним вызовом (сервис ComfyUI, модели, диск)

Related MCP server: comfyui-mcp

Быстрый старт

# 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"

Требования

• macOS с Apple Silicon (MLX / Metal)

• ComfyUI, запущенная локально (по умолчанию 127.0.0.1:8188)

• Окружение Python с пакетом mcp (самому серверу нужны только stdlib + mcp)

• Опционально: mflux + пользовательский узел ComfyUI-mflux-AnyModel для пути MLX

• Опционально: веса FLUX.2 Klein bf16 + текстовый энкодер Qwen3-4B для пути bf16

Настройка модели (Apple Silicon, дружелюбно к 24 ГБ)

Загрузите MLX-модели mflux с помощью кэша HF и создайте на них симлинки в models/mflux/ (см. Кэширование HF / симлинки) — сервер обнаружит их автоматически.

Примечания для Apple Silicon

• Веса fp8 не работают на MPS — сначала конвертируйте в bf16 (деквантизация на стороне CPU). flux-2-klein-4b-bf16.safetensors — это bf16-конверсия официальной контрольной точки fp8.

• Загрузки HF могут зависать в некоторых сетях — export HF_HUB_DISABLE_XET=1 исправляет это.

• Производительность (M4 10-ядерный GPU, 1024×1024): 4B-4bit ~12,7 с/шаг (пик ~11 ГБ), bf16 ~12,1 с/шаг (пик ~15 ГБ).

Кэширование HF и симлинки

HuggingFace snapshot_download хранит реальные данные в ~/.cache/huggingface/hub/models--<org>--<name>/blobs/ и предоставляет симлинки в snapshots/<rev>/. Этот проект хранит симлинки в models/mflux/<Model-Name>/, указывающие на эти снимки — нулевое дублирование дискового пространства, и list_models автоматически их подхватывает.

Устранение неполадок

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

• ComfyUI не отвечает? Убедитесь, что она запущена на 127.0.0.1:8188 (сначала убейте устаревшие экземпляры).

• Модель отсутствует в list_models? Создайте симлинк (или скопируйте) в models/mflux/ с подкаталогом transformer/.

• MCP не отображается в агенте? Перезапустите сессию агента после редактирования config.yaml.

Лицензия

MIT