~/.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)。選用的共享金鑰,從根上限制誰能在你的中繼上開工作階段(
?key=),與按工作階段的橋接權杖無關。
只在中繼模式下有意義,並且只在你的中繼部署設定了 RELAY_ACCESS_KEY 時才有用。任務監視
排入佇列任務的完成通知由監視器追蹤(有 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