comfyui-local-mcp

从 MCP 客户端（Hermes、Claude Code、Cursor 以及任何 MCP 代理）驱动您的本地 ComfyUI——配备专为 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-bit 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 友好）

使用 HF 缓存下载 mflux MLX 模型，并将其符号链接到 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