comfyui-local-mcp

ローカル ComfyUI を MCP クライアント（Hermes、Claude Code、Cursor、任意の MCP エージェント）から操作できるようにします — Apple Silicon（MLX + MPS） 向けに調整済みの FLUX.2 Klein テキスト→画像ワークフローが同梱されています。

ビルド・テスト環境：Mac mini M4 · 24GB ユニファイドメモリ · macOS 26 · ComfyUI 0.33 · mflux 0.19

機能

• 🖼️ generate_image — モデルを自動検出してテキストから画像を生成：

  • mflux:<name> — FLUX.2 Klein 4B / 9B、4 ビット MLX（高速、低メモリ）

  • bf16 — ComfyUI ネイティブ bf16（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"

必要条件

• Apple Silicon（MLX / Metal）搭載の macOS

• ローカルで動作している ComfyUI（デフォルト 127.0.0.1:8188）

• mcp パッケージを含む Python 環境（サーバー自体は stdlib + mcp のみが必要）

• オプション：MLX パス用の mflux + ComfyUI-mflux-AnyModel カスタムノード

• オプション：bf16 パス用の FLUX.2 Klein bf16 重み + Qwen3-4B テキストエンコーダー

モデルセットアップ（Apple Silicon、24GB 対応）

mflux MLX モデルは HF キャッシュを使用してダウンロードし、models/mflux/ にシンボリックリンクを張ってください （HF キャッシュ / シンボリックリンク を参照）— サーバーが自動検出します。

Apple Silicon に関する注意事項

• fp8 重みは MPS では動作しません — 最初に bf16 に変換してください（CPU サイドでの逆量子化）。 flux-2-klein-4b-bf16.safetensors は公式 fp8 チェックポイントを bf16 に変換したものです。

• 一部のネットワークでは HF ダウンロードが停止することがあります — export HF_HUB_DISABLE_XET=1 で修正できます。

• パフォーマンス（M4 10コアGPU、1024×1024）：4B-4bit ~12.7秒/ステップ（ピーク ~11GB）、bf16 ~12.1秒/ステップ（ピーク ~15GB）。

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