Skip to main content

​
是什么

ComfyTV 在你的 ComfyUI 服务器上开放 Model Context Protocol 端点 POST /comfytv/mcp。任何支持 MCP 的 agent(Claude Code,或任何会说 streamable HTTP JSON-RPC 的客户端)都能连上来,把 ComfyTV 当成一套工具使用。 设计上有个关键点:画布的真相在打开着的 ComfyTV 页面里。读工具由服务器直接回答,写工具(加节点、设 prompt、跑渲染)则由打开着的 ComfyTV 页面执行——无论它在 Comfy Desktop 还是浏览器中；服务器通过 websocket 把命令转给它。没有开着的页面 → 写工具会以明确的超时信息失败。

​
启用

MCP 默认关闭。在 ComfyTV 侧边栏打开 设置 → Agent 与 MCP,开启启用 MCP 服务。(内嵌 Bot 还需要它自己的开关。)

​
连接客户端

Claude Code:
Codex:把服务器加到 ~/.codex/config.toml:
其他 MCP 客户端:用 streamable HTTP 指向同一 URL。处理器本身仍是无状态的,但服务器会在 initialize 时签发一个 Mcp-Session-Id,以兼容期望 streamable-HTTP 会话管理的客户端。不在 ComfyUI 之上附加鉴权 — 8188 端口的网络暴露请自行斟酌。

​
工具目录

读取与发现 搭建与运行 原生 ComfyUI 图 看见与评判 配置 富编辑器

​
关键套路

生产循环。stage_catalog → add_stage(prompt、工作流、asset_refs)→ connect_stages → run_stage → wait_stage → outputs → view_image 质检 → 迭代。 不轮询的等待。wait_stage 在服务器侧阻塞(单次默认 25 秒,上限 170 秒),结果一落地立即返回。超时返回 after_output_id — 带着它再调就继续等。总时长无上限,长渲染多续调几次而已。 **@ 序数是从 1 起的位置。**每个节点按类型维护一张有序媒体表 — 连线输入和 asset_refs 在同一张表里,顺序以 get_stage 返回的 media 为准。@image_1 / @video_1 这类 token 按位置寻址(@image_1 就是第一张图)。删除或重排媒体时,节点 prompt 里的 token 会自动重新编号;set_stage 的 media_order 用来重排,connect_stages 会返回这根线落在第几位。越界 token 展开为空 — 工具结果会带警告提醒。 真视觉。view_image 是唯一返回像素的工具。视频质检:先 media_frame 抽帧,再 view_image 亲眼看。别靠文件名猜图。 给新 link 的工作流配绑定。workflow_get 看 API 图节点清单;workflow_edit 用 option:seed、computed:width / computed:height(尺寸引擎)、main_prompt、upstream_image:value[0]、literal:... 这些来源绑定。工作流需要 ComfyTV 没有默认键的参数时,先用 stage_params 建一个,再绑 option:<它的 key>。reset_to_preset 是后悔药。 多机。servers 列出配置的机器和实时负载;set_stage {server: <id>} 把某节点的运行路由过去,结果落回本机。 **两层图。**stage 工具(add_stage/set_stage/…)工作在 ComfyTV 产品层;graph_* 家族直接编辑底下的原生 ComfyUI 图 — 任何插件的任何节点。有现成 stage 就用 stage;要搭裸管线就下到 graph_edit + graph_run,再用 canvas_focus 给用户看你改了哪。 **技能。**用户装了 Agent Skills 时,skill 工具的 description 会列出它们;任务命中就先读再照做。每个启用的技能同时暴露为一条 MCP prompt — 在 Claude Code 里表现为 /mcp__comfytv__<技能名> 斜杠命令,可显式调用。

​
前置条件与行为说明

  • 写工具需要开着的 ComfyTV 页面（Comfy Desktop 或浏览器均可）;画布镜像在首次 MCP 调用后懒激活(刚连上时 get_canvas 等 ~10 秒重试)。
  • MCP 客户端会按会话缓存 tools/list — 服务器加了新工具后需重连。
  • 客户端若有单次工具调用超时,给 wait_stage 传更小的 timeout_s 分片续调。

​
另见