██████╗ ██████╗ ███╗   ███╗███████╗██╗   ██╗██████╗ ██╗██╗      ██████╗ ████████╗
██╔════╝██╔═══██╗████╗ ████║██╔════╝╚██╗ ██╔╝██╔══██╗██║██║     ██╔═══██╗╚══██╔══╝
██║     ██║   ██║██╔████╔██║█████╗   ╚████╔╝ ██████╔╝██║██║     ██║   ██║   ██║
██║     ██║   ██║██║╚██╔╝██║██╔══╝    ╚██╔╝  ██╔═══╝ ██║██║     ██║   ██║   ██║
╚██████╗╚██████╔╝██║ ╚═╝ ██║██║        ██║   ██║     ██║███████╗╚██████╔╝   ██║
 ╚═════╝ ╚═════╝ ╚═╝     ╚═╝╚═╝        ╚═╝   ╚═╝     ╚═╝╚══════╝ ╚═════╝    ╚═╝

ComfyPilot v1.9.0

ComfyPilot 是一个用于 ComfyUI 的 MCP 服务器。 它为 AI 代理提供了一个干净的工具表面，用于工作流构建、队列管理、进度监控、图像检索、快照和 VRAM 安全。

文档

• 生产手册：docs/MANUAL.md

• ComfyUI 版本兼容性审计：docs/COMFYUI_COMPATIBILITY.md

• 发布说明：CHANGELOG.md

Related MCP server: ComfyUI MCP

这是什么

• 一个连接 AI 代理与 ComfyUI 的实用桥梁。

• 一个 96 工具 MCP 表面，用于工作流构建、现代作业检查/取消、模型管理、图像上传/下载、历史记录、监控、快照、技术记忆、VRAM 安全、输出路由、蓝图、Mermaid 可视化、PNG 导入、n 维参数扫描、合作伙伴 API 发现、模型中心搜索、桌面感知实例控制、通用工件、comfy-env 工作器、comfy-cli 生命周期和诊断。

• 实时模型文件夹发现：默认搜索 diffusion_models/、text_encoders/、clip_vision/、style_models/、gligen/（以及连接的 ComfyUI 实际暴露的每个其他文件夹）——不再有以检查点为中心的盲点。

• 一个面向迭代的工作流循环，而非一次性猜测。

• 一个小型技术库，用于保存和重放有效的工作模式。

核心思考模型（如何使用此 MCP）

对于每个非平凡任务，使用此循环：

1. 首先检查系统 - 在加载模型之前读取 GPU 状态。从 comfy_get_system_stats、comfy_check_vram 开始。

2. 检查记忆 - 在从头构建之前，使用 comfy_search_techniques 检查库中是否已存在类似的工作流。

3. 小步构建 - 使用 comfy_build_workflow 实现任何意图（txt2img、img2img、upscale、inpaint、controlnet、txt2video、img2video、image2_3d、txt2music、super_resolution、interpolate_frames、segment、train_lora、txt2audio）。对于按系列路由的意图，系列从已安装的检查点自动检测；对于与系列无关的意图（super_resolution、interpolate_frames、segment、train_lora、txt2audio），无论检查点如何，都按意图名称分发。对于常见配方，从 comfy_insert_blueprint(name="flux2-txt2img") 或 13 个捆绑蓝图中的任何一个开始。在排队之前使用 comfy_validate_workflow 进行验证（6 遍：模式、目录、图、反循环、环境、执行风险）。

4. 监控和检索 - 使用 comfy_queue_prompt 排队，使用 comfy_watch_progress 观察，使用 comfy_get_output_image 检索（直接在聊天中返回图像内容块）。

5. 更改前快照 - 在修改工作工作流之前始终执行 comfy_snapshot_workflow。使用 comfy_diff_snapshots 和 comfy_restore_snapshot 进行撤销。

6. 路由输出 - 使用 comfy_send_to_disk、comfy_send_to_td、comfy_send_to_blender 将生成的图像发送到磁盘、TouchDesigner 或 Blender。

工具地图（96 个工具）

1) 系统 + GPU

用于连接健康检查、GPU 诊断和 VRAM 管理。

• comfy_get_system_stats、comfy_get_gpu_info、comfy_get_features

• comfy_list_extensions、comfy_restart、comfy_free_vram

2) 模型

用于发现和管理 ComfyUI 暴露的每个模型文件。文件夹分类法从 /models 实时发现，因此权重位于 diffusion_models/、text_encoders/、clip_vision/、style_models/ 或 gligen/ 下的现代系列默认被覆盖。

• comfy_list_models - 单个文件夹内的分页列表（folder、limit、offset）。

• comfy_get_model_info - 模型加载器节点类的规范化节点模式。

• comfy_list_model_folders - 来自 GET /models 的实时文件夹列表，当端点不可达时回退到 16 个文件夹的静态默认值。报告 source: live | fallback。

• comfy_search_models - 默认搜索所有已发现的文件夹。传递 folders=["checkpoints", "loras"] 以缩小范围。空查询返回完整清单。

• comfy_refresh_models - 重新获取每个文件夹的缓存；返回每个文件夹的计数 + total_models 数字。

3) 工作流执行

用于排队、取消和管理提示执行。

• comfy_queue_prompt、comfy_get_queue、comfy_cancel_run

• comfy_list_jobs、comfy_get_job、comfy_cancel_jobs

• comfy_interrupt、comfy_clear_queue

• comfy_validate_workflow、comfy_export_workflow、comfy_import_workflow

4) 节点 + 模式

用于探索 ComfyUI 的节点目录和理解小部件模式。

• comfy_list_node_types、comfy_get_node_info、comfy_search_nodes

• comfy_get_categories、comfy_get_embeddings、comfy_inspect_widget

5) 图像 + 视觉输出

用于检索生成的图像（在聊天中作为图像内容块返回）。

• comfy_get_output_image、comfy_upload_image、comfy_list_output_images

• comfy_download_batch、comfy_get_image_url

6) 历史记录

用于检查过去的生成及其输出。

• comfy_get_history、comfy_get_run_result、comfy_delete_history

• comfy_clear_history、comfy_search_history

7) 监控 + 进度

用于跟踪活动作业和观察工作流动态。

• comfy_watch_progress、comfy_subscribe、comfy_unsubscribe

• comfy_get_events、comfy_describe_dynamics、comfy_get_status

8) 工作流快照

用于撤销/恢复和工作流版本跟踪。

• comfy_snapshot_workflow、comfy_list_snapshots、comfy_diff_snapshots

• comfy_restore_snapshot、comfy_delete_snapshot、comfy_auto_snapshot

9) 技术记忆

用于学习、保存和重放可重用的工作流模式。

• comfy_save_technique - 将工作流保存为带有标签和元数据的可重用技术。

• comfy_search_techniques - 通过文本查询和/或标签搜索库。

• comfy_list_techniques - 列出所有已保存的技术及其元数据。

• comfy_replay_technique - 加载已保存的技术工作流以供立即使用。

• comfy_favorite_technique - 将技术标记为收藏并评分（0-5）。

技术存储位于 ~/.comfypilot/techniques/，作为单独的 JSON 文件。

10) 安全 + VRAM 保护

用于护栏、预检和紧急控制。

• comfy_check_vram - 检查 GPU VRAM 使用情况，带有状态级别（ok/warn/critical）。

• comfy_set_limits - 配置安全阈值（警告百分比、阻止百分比、最大队列大小）。

• comfy_detect_instability - 检查接近 OOM 的条件和卡住的作业。

• comfy_validate_before_queue - 预检：VRAM 余量 + 队列容量。

• comfy_emergency_stop - 中断当前作业，清空队列，释放所有 VRAM。

11) 工作流构建器

用于系列感知的模板构建和节点编辑。

• comfy_build_workflow - 系列感知：检测检查点系列（SD 1.5、SDXL、SD 3.5、Flux 2、Qwen-Image、Wan 2.2、LTX-2、HunyuanVideo、Hunyuan3D、ACE-Step）并分派到正确的图拓扑。意图：txt2img、img2img、upscale、inpaint、controlnet、txt2video、img2video、image2_3d、txt2music。

• comfy_add_node - 向进行中的工作流添加节点。

• comfy_connect_nodes - 将节点输出连接到输入。

• comfy_set_widget_value - 设置节点上的小部件值。

• comfy_apply_template - comfy_build_workflow 的别名。

12) 输出路由

用于代理编排的跨应用交付生成的图像。

• comfy_send_to_disk - 将输出图像保存到本地文件系统。

• comfy_send_to_td - 将输出路由到 TouchDesigner 项目目录。

• comfy_send_to_blender - 将输出路由到 Blender 项目目录。

• comfy_list_destinations - 列出已配置的输出目标。

13) 子图蓝图

用于从命名的可重用宏组装工作流。

• comfy_list_blueprints - 列出所有可用的蓝图（用户 + 捆绑）。

• comfy_insert_blueprint - 将蓝图物化为工作流字典，带有可选的每节点输入覆盖。

• comfy_publish_subgraph - 将一组节点保存为可重用的命名蓝图。

蓝图存储：用户发布的位于 ~/.comfypilot/blueprints/（通过 COMFY_BLUEPRINT_DIR 覆盖）；捆绑示例位于仓库内的 blueprints/ 中。

14) 可视化 + 导入 + 扫描

用于渲染工作流、重新导入 PNG 输出和参数扫描。

• comfy_visualize_workflow - 将 API 格式的工作流渲染为 Mermaid flowchart TD 源代码。

• comfy_import_workflow_from_png - 从 ComfyUI 保存的 PNG 中提取嵌入的工作流 JSON（优先使用 'prompt' API 格式块，回退到 'workflow' UI 块）。

• comfy_sweep - 将工作流的 N 个副本排队，单个参数在 values 中变化；返回 prompt_ids + 网格布局提示。

• comfy_sweep_grid - 在多个 node_id.param 轴上的 N 维笛卡尔积扫描。默认上限为 64 种组合（通过 max_combinations 覆盖）。

15) 模型中心搜索

用于发现要从公共中心下载的模型。

• comfy_search_hub - 在 HuggingFace 或 CivitAI 上搜索与查询匹配的模型。返回标准化结果（id、name、url、downloads、tags）。使用 source="huggingface" 或 source="civitai"。

16) 合作伙伴 API

用于显示哪些供应商托管的合作伙伴/API 自定义节点已安装。

• comfy_list_partner_apis - 将 ComfyUI 的已安装扩展列表与精选目录（Veo、Kling、ByteDance Seedance/Seedream、GPT-Image、Topaz、Tripo3D、Rodin、Recraft、Ideogram、NanoBanana、Sonilo、ElevenLabs 等）相交，并报告哪些在此服务器上处于活动状态，带有供应商/类别/主页元数据。

17) 生命周期（v1.8.0）

用于在 ComfyUI 尚未运行时进行完整的设置到服务器流程。所有五个工具都调用官方的 comfy-cli — 通过 pipx install comfy-cli 或 uvx --from comfy-cli comfy ... 安装。

• comfy_launch_server - 启动 ComfyUI（comfy launch --background --port N --listen H）。

• comfy_stop_server - 停止正在运行的服务器（comfy stop）。

• comfy_install_node - 通过 Comfy Manager 按 slug 安装自定义节点包。

• comfy_list_installed_nodes - 列出当前安装的自定义节点。

• comfy_download_model - 通过 URL 将模型下载到选定的 models/<folder>（支持 CivitAI 令牌）。

18) 诊断（v1.8.0）

用于工作流内省、硬件判定、回溯提取和信任检查。

• comfy_extract_schema - 工作流级别的可控参数与依赖摘要（参数列表、模型依赖、嵌入引用、输出节点，支持summary_only模式）。

• comfy_fetch_logs - 从/history/{prompt_id}中提取仅包含错误回溯和已完成节点列表的信息——同时处理status.exec_info.errors和status.messages两种格式。

• comfy_inspect_workflow - 信任检查：将每个class_type分类为内置/自定义，并在队列化不受信任的工作流之前显示警告。

• comfy_recommend_runtime - 硬件评估（ok/marginal/cloud）以及针对此硬件的正确comfy-cli安装标志。

• comfy_suggest_timeout - 基于长时间运行的输出类别的每个工作流HTTP超时建议（默认300秒，训练时最高3600秒）。

19) 便捷工具 (v1.8.0)

用于压缩代理通常需要手动编写脚本的多步骤流程。

• comfy_install_workflow_deps - 自动安装工作流引用的所有缺失的自定义节点包（封装了comfy node install-deps --workflow）。

• comfy_run_with_inputs - 上传本地图像 + 注入为工作流输入 + 队列化——将三步的img2img/inpaint流程压缩为一次调用。

• comfy_randomize_seeds - 将seed=-1哨兵值替换为密码学级别的随机uint32值；force=True会随机化所有种子控件。

20) 桌面实例 + 工件 + 工作进程

用于控制确切连接的桌面安装，而不是猜测工作区或端口。

• comfy_instance_doctor - 解析连接的PID、所有者/主管、端口、代码/数据/用户/输入/输出/模型根目录、桌面安装、版本和安全警告。

• comfy_list_artifacts - 列出图像、视频、音频、网格和其他输出，并在历史记录重置后提供本地输出目录回退。

• comfy_get_artifact - 解析一个输出工件的安全元数据，防止路径遍历。

• comfy_get_environment_status - 检查已配置/缓存的comfy-env环境和运行时健康状态。

• comfy_list_workers - 列出活动的隔离工作进程、PID、环境和健康状态。

MCP 资源

六个固定资源：

• comfy://system/info - 系统统计信息、GPU信息、ComfyUI版本

• comfy://server/capabilities - 检测到的服务器配置文件、版本、前端版本、认证方法、WebSocket可用性、OpenAPI版本、缓存提供程序

• comfy://nodes/catalog - 节点目录预览（前100个名称）

• comfy://models/{folder} - 按文件夹列出的模型（checkpoints、loras、vae、diffusion_models、text_encoders等）

• comfy://embeddings - 可用的嵌入

• comfy://api/openapi - 当连接的部署暴露/openapi.json时，可选的OpenAPI 3.1摄取；否则返回{"error": ...}。

另外四个资源模板（参数化URI）：

• comfy://nodes/catalog/{page} - 分页节点目录，每页100个节点（{page} = 0, 1, 2, ...）

• comfy://nodes/by-category/{category} - 类别以给定前缀开头的节点class_type（例如sampling、loaders/video）

• comfy://templates/catalog - ComfyUI核心和自定义节点广告的工作流模板（通过/workflow_templates）

• comfy://docs/{node_class} - 来自/docs/<class>/en.md的本地化嵌入式Markdown，带有结构化分支和对象信息回退。

如何使用（实用工作流）

1. 将MCP客户端连接到ComfyPilot。

2. 检查系统状态和VRAM余量。

3. 构建工作流（模板或自定义API JSON）。

4. 验证，然后队列化提示。

5. 观察进度直到完成。

6. 检索输出图像（在聊天中内联显示）。

7. 如果需要，路由到磁盘/TD/Blender。在稳定里程碑处创建快照。

擅长领域

• 通过对话构建和迭代ComfyUI工作流。

• 跨11个模型系列（SD 1.5、SDXL、SD 3.5、Flux 2、Qwen-Image、Wan 2.2、LTX-2、HunyuanVideo、Hunyuan3D、ACE-Step、Ernie Image）的系列感知生成，涵盖图像、视频、3D网格和音乐。外加5个系列无关意图（通过SUPIR的超分辨率、通过RIFE/FILM的帧插值、通过SAM 3.1的分割、原生LoRA训练、通过Stable Audio的文本到音频）。

• 从每个系列的捆绑蓝图开始（仓库内包含13个）并在此基础上进行定制。

• 6遍工作流验证（模式+目录+图+反循环+环境+执行风险），在到达ComfyUI之前捕获断链、循环、缺失模型、已弃用模型、过大的潜在表示。

• 通过VRAMGuard监控GPU资源并防止OOM情况。

• 直接在聊天中返回生成的图像（图像内容块）。

• 跨应用输出路由到TouchDesigner和Blender，具有原子写入和侧车清单（prompt_id、种子、模型引用、尺寸）。

• 用于非破坏性工作流实验的快照/恢复，现在可选择在重启后持久化。

• 通过技术库学习和重放可重用的工作流模式。

• 参数扫描（队列化单个控件值的N个变体）。

• 从保存的PNG的嵌入元数据中导入工作流。

• 将任何工作流渲染为Mermaid以进行快速视觉检查。

• 直接在HuggingFace和CivitAI上搜索模型。

不擅长领域

• 自行替代艺术指导。

• 流式传输实时视频输出（快照和轮询，而非实时帧）。

• 无需迭代优化的“一次性完美生成”。

• 在没有可用的ComfyUI实例（云端或本地）的情况下运行。生命周期工具（comfy_launch_server、comfy_install_node、comfy_install_workflow_deps、comfy_download_model）可以将本地安装从零开始准备就绪，但它们需要PATH上的comfy-cli——首先通过pipx install comfy-cli或uvx --from comfy-cli comfy ...安装。

模型系列

11个一级模型系列外加5个系列无关的意图覆盖。每个系列都有一个（或多个）构建器模板，可生成匹配正确图拓扑的工作流。系列从检查点文件名检测；您可以通过传递checkpoint=参数来覆盖。意图覆盖完全跳过系列检测，并按意图名称分发。

意图覆盖（系列无关；按意图名称分发，无论检测到的检查点系列如何）：

传输方式

• stdio（默认） - 最适合本地客户端，如Claude Code、Claude Desktop、Cursor。

• streamable-http - 最适合托管/远程部署。使用以下方式启用：

uv run comfypilot --transport streamable-http --host 0.0.0.0 --port 8765

支持矩阵

快速设置

选项 1：MCPB（一键安装，Claude Desktop）

Claude Desktop 用户最简单的方式：

1. 从最新发布下载 comfypilot-v1.9.0.mcpb。

2. 双击该文件（或将其拖入 Claude Desktop 的设置 > 扩展面板）。

3. Claude Desktop 会显示一个表单，包含 COMFY_URL、COMFY_API_KEY 和其他配置字段——填写所需内容。

4. 点击安装。重启会自动处理。

MCPB 使用 type: "uv" 服务器模式，因此 Python 依赖项（mcp、httpx、pydantic、websockets）会在首次运行时由 uv 解析。你需要在主机上安装 uv——安装 uv。

该捆绑包包含 manifest.json + pyproject.toml + 完整的 src/comfy_mcp/ 包 + 13 个捆绑蓝图。清单：manifest.json。

选项 2：本地开发运行时

git clone https://github.com/dreamrec/ComfyPilot.git
cd ComfyPilot
uv sync
uv run comfypilot

选项 3：Claude Code 插件

claude plugin add /path/to/ComfyPilot

选项 4：Codex

安装检出并注册其 stdio 服务器：

uv sync
codex mcp add comfypilot --env COMFY_URL=http://127.0.0.1:8188 -- uv run --directory /path/to/ComfyPilot comfypilot

Codex 将 MCP 配置存储在 ~/.codex/config.toml 中；CLI、IDE 扩展和桌面应用程序共享该配置。更改 MCP 服务器后请重启 Codex。

本地覆盖

如果你的 ComfyUI 实例位于 127.0.0.1:8188 以外的位置（Tailscale、远程局域网、自定义端口），请将 .mcp.local.json.example 复制为 .mcp.local.json 并进行编辑。.mcp.local.json 文件已被 gitignore，因此每台机器的 URL 和密钥永远不会被提交。

MCP 捆绑包（标准化）

ComfyPilot 在仓库中附带一个标准 MCP 捆绑包：

• mcp/manifest.json

• mcp/profiles/claude-desktop.json、cursor.json、generic.json

捆绑的配置文件 JSON 使用 uv run 并指定 --directory；在复制到客户端配置时，请将 /path/to/ComfyPilot 替换为你的检出路径。如果你在此仓库内启动，.mcp.json 已使用 ${CLAUDE_PLUGIN_ROOT}。

手动客户端配置示例（Claude Desktop）：

{
  "mcpServers": {
    "comfypilot": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/ComfyPilot", "comfypilot"],
      "env": {
        "COMFY_URL": "http://127.0.0.1:8188",
        "COMFY_API_KEY": ""
      }
    }
  }
}

环境变量

测试套件

运行测试套件：

uv run pytest -v

运行特定类别：

uv run pytest tests/test_builder.py -v

快速冒烟测试：

uv run pytest -q

可靠性习惯

将此视为每个有意义任务的强制性要求：在生成前检查 VRAM，在工作流更改前创建快照，在构建后验证，在错误后运行 comfy_detect_instability。

许可证

MIT

dreamrec // ComfyPilot // live laugh diffuse