comfyui-local-mcp

Betreiben Sie Ihre lokale ComfyUI von MCP-Clients aus (Hermes, Claude Code, Cursor, jeder MCP-Agent) — mit fertigen FLUX.2 Klein Text-zu-Bild-Workflows, optimiert für Apple Silicon (MLX + MPS).

Erstellt und getestet auf: Mac mini M4 · 24GB unified memory · macOS 26 · ComfyUI 0.33 · mflux 0.19

Features

• 🖼️ generate_image — Text-zu-Bild mit automatischer Modellerkennung:

  • mflux:<name> — FLUX.2 Klein 4B / 9B, 4-bit MLX (schnell, wenig Speicher)

  • bf16 — ComfyUI-natives bf16 (MPS, beste Qualität)

  • auto — wählt automatisch das beste Modell aus (9B bevorzugt)

• 📦 list_models — listet installierte Modelle auf (scannt automatisch models/mflux/, füge Modelle ohne Codeänderungen hinzu)

• 🗂️ list_outputs — kürzlich generierte Bilder

• 🩺 system_status — Diagnose mit einem Aufruf (ComfyUI-Dienst, Modelle, Festplatte)

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 mit Apple Silicon (MLX / Metal)

• ComfyUI lokal ausgeführt (Standard 127.0.0.1:8188)

• Python-Umgebung mit dem Paket mcp (der Server selbst benötigt nur stdlib + mcp)

• Optional: mflux + benutzerdefinierter Knoten ComfyUI-mflux-AnyModel für den MLX-Pfad

• Optional: FLUX.2 Klein bf16-Gewichte + Qwen3-4B-Textencoder für den bf16-Pfad

Model setup (Apple Silicon, 24GB friendly)

Laden Sie mflux MLX-Modelle mit HF-Cache herunter und verlinken Sie sie symbolisch in models/mflux/ (siehe HF-Caching / Symlinks) — der Server erkennt sie automatisch.

Apple Silicon notes

• fp8-Gewichte funktionieren nicht auf MPS — zuerst in bf16 konvertieren (eine CPU-seitige Dequantisierung). flux-2-klein-4b-bf16.safetensors ist eine bf16-Konvertierung des offiziellen fp8-Checkpoints.

• HF-Downloads können in manchen Netzwerken hängen bleiben — export HF_HUB_DISABLE_XET=1 behebt das.

• Leistung (M4 10-Kern-GPU, 1024×1024): 4B-4bit ~12.7s/Schritt (Spitze ~11GB), bf16 ~12.1s/Schritt (Spitze ~15GB).

HF caching and symlinks

HuggingFace snapshot_download speichert die eigentlichen Daten in ~/.cache/huggingface/hub/models--<org>--<name>/blobs/ und legt Symlinks unter snapshots/<rev>/ an. Dieses Projekt behält Symlinks in models/mflux/<Model-Name>/, die auf diese Snapshots verweisen — keine doppelte Festplattennutzung, und list_models erkennt sie automatisch.

Troubleshooting

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

• ComfyUI antwortet nicht? Stellen Sie sicher, dass es auf 127.0.0.1:8188 läuft (töten Sie zuerst veraltete Instanzen).

• Modell fehlt in list_models? Verlinken Sie es symbolisch (oder kopieren Sie es) in models/mflux/ mit einem Unterverzeichnis transformer/.

• MCP im Agenten nicht sichtbar? Starten Sie die Agentensitzung nach dem Bearbeiten von config.yaml neu.

License

MIT