~/.claude/settings.json 里的 env 块中)或
CLI 标志完成。ComfyUI 目标的优先级:
--comfyui-url / COMFYUI_URL → COMFYUI_HOST/COMFYUI_PORT → 自动检测。
部署模式
comfyui-mcp 在三种模式之一下运行,由环境自动选定:
需要本地安装的工具(
restart_comfyui 配合 action: "start" / apply_manifest /
list_local_models(action:"remove")/ get_image (action:"list_outputs") / 等等)
在远程或云端模式下会返回明确错误。远程和云端模式下服务器会跳过本地 COMFYUI_PATH
自动检测,这样过时的本地安装就不会悄悄把智能体本想发给实际目标的上传或模型下载吃掉
—— 如果你想混搭,请显式设置 COMFYUI_PATH。
连接
ComfyUI 实例的完整 URL,例如
https://my-comfy.example.com。等价于
--comfyui-url CLI 标志。优先于 host/port,并跳过端口自动检测。
路径前缀会被保留(例如 https://host/comfyapi),这样反代实例能正确路由。当主机
是非回环(除 127.0.0.1 / localhost / ::1 / 0.0.0.0 以外的任何地址)时,
服务器进入远程模式并跳过 COMFYUI_PATH 自动检测。用于分离式安装的可选代码 checkout 根目录;此时
main.py 和 .venv 与数据及模型
分开存放。pip / venv / 核心更新使用此路径。节点包读写(custom_nodes)仍落在
--base-directory / COMFYUI_PATH。远程模式下不会用它修改本地文件系统。用于重启外部托管 ComfyUI 的 shell 命令 — 例如
docker restart comfyui 或
systemctl --user restart comfyui。设置后,restart_comfyui 会运行该命令而不是
kill+relaunch(后者要求能解析安装目录的启动路径 — 对于容器或启动器来说不可能,
因为它们的 main.py 只在自己的命名空间内可定位),panel_restart_comfyui
也同样经由该命令。仅对本地目标生效;远程 / 云端目标仍走 Manager 重启路径。
重启会验证实例恢复健康,只有实际观测到 down→up 时才报告为 confirmed。反向代理 / API 网关后面的远程实例
面向暴露在路径前缀和 / 或自有认证层后面的自建 ComfyUI(nginx 路由、API 网关、SSO 边缘) —— 这不是 Comfy Cloud:COMFYUI_URL会保留路径前缀(例如https://host/comfyapi),于是请求走在它下面, 而不是打到根上的/prompt、/system_stats……COMFYUI_AUTH_*变量给每一次 ComfyUI 请求挂上通用认证头(直接 HTTP 调用以及底层 客户端 / WebSocket 库)。这与云端模式无关,所以走网关认证的实例永远不会被误读成 Comfy Cloud。
Cloudflare Access 服务令牌 Client ID。与
CF_ACCESS_CLIENT_SECRET 一起设置,
才能到达挡在 Cloudflare Access 前面的 ComfyUI —— 两者会(作为
CF-Access-Client-Id / CF-Access-Client-Secret)发在每一次 ComfyUI 请求上
(HTTP 和队列监视器 WebSocket),于是连接器能过 Access 门,而不是拿到交互式登录页。
与 COMFYUI_AUTH_TOKEN 相加;两者都设置时都生效。从不记入日志。Cloudflare Access 服务令牌 Client Secret(
CF_ACCESS_CLIENT_ID 的配对)。
只有两者都设置时才会发送 —— 配了一半的令牌会被忽略。从不记入日志。Comfy Cloud
设置COMFYUI_API_KEY 会把服务器切进云端模式:所有基于 HTTP 的原语(入队、历史、
系统状态、队列、查看、上传)经 HTTPS 路由到 cloud.comfy.org,并用 X-API-Key 认证;
WebSocket 和本地 FS / 进程工具会抛出明确的 CLOUD_UNSUPPORTED 错误。架构和
cloud-client 调度最初由 @picoSols 贡献。
Comfy-Org 提供 官方智能体工具 —— Comfy Cloud MCP(公开测试版)和 Comfy In-App Agent(私有内测版),都由 Comfy 团队维护,都跑在 Comfy Cloud 上。如果你只瞄准 Comfy Cloud,那多半是正确选择;见 本地 vs. Comfy Cloud。下面
comfyui-mcp 的云端模式最适合你想用一个 MCP 覆盖本地 / 远程 / 云端,或你今天就需要它的时候(MIT,现在就在发货)。令牌
面向网络受限地区的 HuggingFace 镜像端点(例如
https://hf-mirror.com)。所有 huggingface.co API 和下载 URL 都会改写到这个主机;
你的 HUGGINGFACE_TOKEN 仍会跟着走,给有门禁的仓库用。这是事实上的标准变量 ——
huggingface_hub 认的就是它。设为
0 可完全禁用 Civitai 访问(civitai.com 不可达的地区)。用户主动发起的
Civitai 工具会立刻以明确的「已被配置禁用」消息失败;后台出处查找会安静地空操作。通过
/prompt 的 extra_data 载荷转发给托管 API 节点的 comfy.org API 密钥。
如果环境变量未设置,密钥会从 ~/.comfy-api-key 读取(去掉首尾空白的文件内容;
建议 chmod 600)—— 方便无界面环境把秘密留在环境 / 进程列表之外。行为
模型下载
每个模型下载使用的并行连接数。单条连接受往返时延限制,在许多模型 CDN 上还受每连接限速;并行拉取字节范围可以突破这两者。设为
1 则关闭该机制,使用单连接下载。仅在文件主机声明支持字节范围、并在探测请求中证实时才启用——否则下载与此前完全一样走单连接。进程监管(本地安装)
适用于 comfyui-mcp 管理本地 ComfyUI 进程时的restart_comfyui(动作 start 和
restart)。
报告启动尚未确认之前的最大就绪探测次数。按默认 1 秒间隔,这是大约 60 秒的预算。
它从 20 提高过来,因为带一套正常自定义节点的 ComfyUI 冷启动时,经常超过 20 秒才
回答
/system_stats,更短的预算会在健康实例即将就绪的前一刻报告启动未确认。预算耗尽意味着启动尚未确认 —— 不是它失败了。面板编排器与桥接
comfyui-mcp-panel 侧边栏由面板编排器 驱动 —— 一个后台进程,拥有回环 WebSocket 桥接,并在你的 Claude 订阅上为每个面板 标签页跑一个自主 Claude Agent SDK 会话(无需 API 密钥)。面板包会在 ComfyUI 加载时 自动启动它,所以通常不用手跑任何东西 —— 见 侧边栏面板。要自己跑:编排器队列 / 渲染监视狗的渲染停滞阈值(秒):正在跑的任务如果节点 / 进度这么久没有
推进,就会被标成停滞,并在智能体下一轮前面预置一行 STALL/BACKLOG 说明。视频步骤
本来就慢,所以默认值偏高。夹在 15–3600 秒。面板的渲染停滞警告(秒)设置
(设置 → Comfy MCP Agent → General)会通过
set_config 桥接帧实时覆盖它 ——
不用重连 —— 并优先于这个环境变量值。安全桥接(驱动远程 / 云端实例)
当connect <url> 瞄准一台远程 https ComfyUI(例如 RunPod 实例)时,实例的 HTTPS
面板页面没法对你机器上的桥接打开普通 ws://127.0.0.1 套接字 —— 浏览器会拦(混合内容 /
Private Network Access)。编排器会自动升级到安全 wss:// 隧道,于是不用提示、任何
浏览器都能用。完整走查见 云端部署;要跑自己的隧道基础
设施而不是默认 cloudflared 快速隧道,见 自建中继。
即使在驱动远程 https 目标时,也强制使用普通回环
ws:// 桥接,而不是自动升级到安全
隧道。如果你通过自己的 SSH 端口转发到达实例(于是它的页面已经是回环源),又不想有
Cloudflare 依赖,就用这个。与 --insecure-bridge 相同。远程目标用哪一种安全桥接后端:
cloudflared(默认 —— 一条临时快速隧道,零配置)或
relay(拨到你运维的 自建中继,换稳定域名、没有第三方
快速隧道依赖)。只在安全模式激活时生效(远程 https 目标,且没有
COMFYUI_MCP_INSECURE_BRIDGE)。任务监视
入队任务的完成通知由监视器跟踪(有 WebSocket 就用,否则 HTTP 轮询)。queue(action:“cancel”)的取消兑现窗口(秒):等待中断真正停下正在跑的任务多久,
再升级(到 /free,然后报告渲染 WEDGED)。ComfyUI 只在节点 / 步骤之间检查中断标志,
所以持续好几分钟的单步不会立刻理会它 —— 这段等待就是用来检测真正楔死的。限制工具面
对托管部署 —— 共享的 Open WebUI、团队前端 —— 操作员不是那个在提示的人。工具预设 / 允许 / 拒绝变量会把工具从模型那里完全扣下:被扣下的工具从不注册,所以它不在tools/list 里,不在 call_tool 里,模型也永远不知道它存在。动作允许列表是必须保持
可见的工具的更窄伴侣:工具仍注册,但未列出的动作会在处理器跑之前被拒绝。
safe —— 除了会改机器或模型库的工具之外的一切。安装、删除和重启被扣下。渲染仍然
能用,随之而来的那些也能用:入队生成、list_api_nodes(会花付费积分的托管合作
节点),以及 report_issue(提交公开 GitHub issue)。如果共享前端的用户不能花钱或
发布,请用 readonly。
readonly —— 只检查:不入队渲染,不写任何东西,不花钱。
两者也会扣下整块 panel_* 面,因为它驱动的是实时共享画布。逗号分隔的允许列表。设置后,工具面正好是这些工具 —— 没点名的一律扣下,即使没有任何
拒绝规则提到它。用它把个别工具从预设里捞回来:
COMFYUI_MCP_TOOL_PRESET=safe 加上
COMFYUI_MCP_TOOL_ALLOW=panel_graph_outline,panel_query_graph。只有确切名字才能把工具从预设里捞回来。通配(list_*)会像其他条目一样收窄工具面,
但不能重新打开预设关掉的东西 —— 否则 ALLOW=list_* 会把 list_packs 重新放进来,
它的 install_deps 动作会安装并运行第三方代码,而 ALLOW=* 会让每个预设都失效。逗号分隔、确切的
tool:action 对。设置后,每一个带 action 字段的工具调用都必须匹配
其中一对;没出现在列表里的带动作工具不能派发任何动作。这用来限制名字本身已经看不出
杀伤半径的合并工具 —— 例如,允许队列检查和定向取消,同时不允许队列编辑或全局清空:queue:list,queue:status,queue:cancel,enqueue_workflow:enqueue把它和 COMFYUI_MCP_TOOL_ALLOW 配对,两个维度都能圈住。规则是确切的;通配会被拒绝,
这样升级后新加的动作不会自动被允许。A hosted deployment that cannot install or restart anything
A generation operator that can inspect, enqueue, and cancel—but not install or clear queues
传输
服务器默认说 stdio(Claude Code 期望的)。它也可以为远程 / 多客户端设置提供 streamable-HTTP 传输。Run the HTTP transport