comfyui-local-mcp

Drive your local ComfyUI from MCP clients (Hermes, Claude Code, Cursor, any MCP agent) — with ready-made FLUX.2 Klein text-to-image workflows tuned for Apple Silicon (MLX + MPS).

Built and tested on: Mac mini M4 · 24GB unified memory · macOS 26 · ComfyUI 0.33 · mflux 0.19

Features

• 🖼️ generate_image — text-to-image with auto model discovery:

  • mflux:<name> — FLUX.2 Klein 4B / 9B, 4-bit MLX (fast, low memory)

  • bf16 — ComfyUI-native bf16 (MPS, best quality)

  • auto — picks the best model automatically (9B preferred)

• 📦 list_models — list installed models (auto-scans models/mflux/, add models without code changes)

• 🗂️ list_outputs — recent generated images

• 🩺 system_status — one-call diagnosis (ComfyUI service, models, disk)

Related MCP server: comfyui-mcp

Quickstart

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

Requirements

• macOS with Apple Silicon (MLX / Metal)

• ComfyUI running locally (default 127.0.0.1:8188)

• Python env with mcp package (the server itself only needs stdlib + mcp)

• Optional: mflux + ComfyUI-mflux-AnyModel custom node for the MLX path

• Optional: FLUX.2 Klein bf16 weights + Qwen3-4B text encoder for the bf16 path

Model setup (Apple Silicon, 24GB friendly)

Download mflux MLX models with HF cache and symlink them into models/mflux/ (see HF caching / symlinks) — the server auto-discovers them.

Apple Silicon notes

• fp8 weights don't work on MPS — convert to bf16 first (a CPU-side dequantize). flux-2-klein-4b-bf16.safetensors is a bf16 conversion of the official fp8 checkpoint.

• HF downloads can stall in some networks — export HF_HUB_DISABLE_XET=1 fixes it.

• Performance (M4 10-core GPU, 1024×1024): 4B-4bit ~12.7s/step (peak ~11GB), bf16 ~12.1s/step (peak ~15GB).

HF caching and symlinks

HuggingFace snapshot_download stores real data in ~/.cache/huggingface/hub/models--<org>--<name>/blobs/ and exposes symlinks under snapshots/<rev>/. This project keeps symlinks in models/mflux/<Model-Name>/ pointing at those snapshots — zero duplicate disk usage, and list_models picks them up automatically.

Troubleshooting

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

• ComfyUI not responding? Make sure it runs on 127.0.0.1:8188 (kill stale instances first).

• Model missing from list_models? Symlink (or copy) it into models/mflux/ with a transformer/ subdir.

• MCP not visible in the agent? Restart the agent session after editing config.yaml.

License

MIT