使用工具 - ComfyUI MCP

工具参考按 AI 阅读的形式列出这个项目能做的一切。本页是给你看的版本。

这里不要求你写代码、打 JSON，或学一套 API。如果你曾经对人说过「打开我的肖像工作流，把步数调到 30」，你已经知道这个界面了。

工具是智能体可以做的事，不是你要输入的东西

单靠自己，聊天模型只能产出文本。它可以描述一条工作流；它打不开一条。工具是我们交给模型的、具体、有名字的动作，好让它真正够到你的 ComfyUI —— 加载文件、把渲染入队、安装节点包、看刚出来的那张图。模型不能发明这些。它拿到一份固定菜单，菜单上每一项都精确说明自己需要什么。 你从不从那份菜单里挑。 你用自然冒出来的词说想要什么，智能体来选。

你说	它悄悄跑的
「我存了些什么？」	`get_workflow` with `action: "list"`
「打开那个肖像的，告诉我它做什么」	`get_workflow` with `action: "list"`，然后 `action: "analyze"`
「给我做一只雪地里的红狐狸」	`generate_image`（`image` 任务）
「做好了吗？」	`queue`（`list` 任务）
「失败了，我不明白为什么」	`get_history`（`diagnose` 任务）
「一半节点都是红的」	`list_packs`（`install_deps` 任务）
「磁盘满了，哪些大？」	`list_local_models`

注意第二行：一句话，两个工具，顺序你不必知道。这就是整套安排的要点。你不需要知道找文件和读文件是两步操作。

你想多含糊都可以。「有东西坏了」就是很好的开头 —— 智能体会从 get_system_stats (action:"health") 开始往下收。说得具体会更快，但从来不是必须的。

参考页里那些 JSON 是什么？

每个工具页都会展示这样一块：

{
  "tool": "generate_image",
  "arguments": {
    "prompt": "a red fox in deep snow, golden hour, sharp focus",
    "steps": 30
  }
}

那是智能体发出去的记录，不是给你的说明书。你说的是「给我做一只雪地里的红狐狸，细节再多一点」；从另一头出来的就是这个。值得能读懂一份，理由有两个：你想核对智能体是不是听懂了，以及出问题时你要跟别人描述。不值得背下来。

工具来自两个地方

有两面，它们存在是因为回答的是不同问题。

侧边栏面板

住在 ComfyUI 里面，智能体标签页里。它的工具（panel_*）作用在你此刻看着的节点图上 —— 那块真实画布，带着你还没保存的改动。

外面的客户端

Claude Desktop、Claude Code、编辑器、你的手机。它的工具作用在服务器上：磁盘上的文件、任务队列、模型、节点包、ComfyUI 进程本身。

分界其实是「这个」这个词。你说「给这个加一个 LoRA」时，面板知道「这个」是什么，因为它看得见你的屏幕。外面的客户端看不见 —— 得告诉它一个文件名。所以面板处理的是这类事：

读你眼前的节点图（panel_graph_outline）
跑它，就跟你自己按了 Queue Prompt 一模一样（panel_run）
接进一个节点、改一个控件、告诉你节点为什么变红（panel_add_node、panel_set_widget、panel_get_errors）
把整条工作流加载到画布上，或保存画布上现有的（panel_load_workflow、panel_save_workflow）

而外面的客户端处理的是从零生成一张图、管理模型和节点包、过一遍已保存的文件、重启 ComfyUI。

如果你是新手，用面板。 一次安装，就在节点图旁边，也不需要单独的应用。见面板指南完成设置。等你想让智能体插手不是画布的事情时，再加外面的客户端。

它们不是对手 —— 面板在底下跟同一台服务器说话，一个会话可以两边都用。有人在桌面上改节点图，同时手机驱动同一个会话，这是受支持的事，不是旁门。

一个工具，多项工作

你会注意到有些工具带一个 action：

{ "tool": "workspace", "arguments": { "action": "get" } }

这看起来像暗号，其实不是。workspace 是一个话题 —— 我们在说哪一份 ComfyUI 安装 —— 而 action 说你就这个话题问的是哪一个问题：读它、改默认、列出有什么。读起来就跟日常说话一样，动词和宾语是分开的词：

你说	动作
「我在用哪份 ComfyUI？」	`get`
「以后一直用 D 盘那份」	`set_default`
「你能看见哪些安装？」	`list`

没有删掉任何东西

这种形状还比较新，很容易读成能力被砍了。并没有，而这种误会值得正面先拦住，因为它已经出现过。以前是一个问题一个工具 —— 读工作区一个名字，设置另一个，列出再一个。那些名字没了，如果你盯着工具数量看，会看见它在急剧下降。实际发生的是相关工具被合并了，不是删除：

The old name	The same thing today
`get_workspace`	`workspace` with `action: "get"`
`get_queue`	`queue` with `action: "list"`
`apps_run_status`	`apps` with `action: "run_status"`
`install_workflow_dependencies`	`list_packs` with `action: "install_deps"`
`list_workflows`	`get_workflow` with `action: "list"`
`analyze_workflow`	`get_workflow` with `action: "analyze"`
`validate_workflow`	`create_workflow` with `action: "validate"`

底下的代码一样，行为一样，答案一样。只有前面的标签变了。原因是菜单长到开始伤人。每个工具的完整描述都得在模型选择之前交给它，过了某个体量，选择本身就会变差 —— 尤其是较小的模型，会开始挑一个看起来像邻居的，而不是对的那个。更少、更宽、带着清楚 action 的工具，实测能修好这个。这也意味着模型把注意力花在你的请求上，而不是读一份目录。这些你都不该察觉。你以前也没打过旧名字；你说的是「我在用哪份 ComfyUI？」，这句话现在仍然管用。

如果某份更旧的指南，或模型自己的记忆，伸手去够一个已经不存在的名字，你会拿到一条点名替代品的具体错误，而不是空白的「未知工具」—— 例如：removed in 0.49.0. Call workspace (action:“get”) instead. 智能体通常能自己纠正并重试，你什么都不用做。

想要不一样的结果

每个工具页都列出参数 —— max_chars、limit、depth、fields。你会合理地问它们该打在哪，诚实的答案是：哪都不打。没有给 max_chars 的设置框，因为它不是一项设置。它是 智能体每次调用工具时当场填的参数。这并不把你排除在外。它改的是控制长什么样：

你不设置参数。你开口要一个 —— 就写在你本来就要写的那句话里。

两种问法

两种都管用。它们失败的方式不同，这是唯一需要两种都知道的理由。

	听起来像	什么时候用
白话	「详细读节点 42 —— 只要那个节点，不要整张图。」	永远从这里开始。这是人们实际会打的，而且通常管用。
显式	「用 `panel_query_graph`，`ids` 为 [42]，`max_chars` 为 20000。」	模型已经错过一次，你想不给它留下余地。

点名工具和参数不是正确形式 —— 它是强硬形式。留给重试。

答案被截断时

长读取会封顶，免得一张巨大的节点图吞掉整段对话。两个不同的天花板可以停住同一次读取 —— 列出的节点数（limit）和字符预算（max_chars）—— 调高那个不是问题的，什么都不会变，读起来就跟重试失败一模一样。你不需要自己算是哪一个。在已保存的文件上，说明会点名触发的那根杠杆，并排除另一根，原话就是这么说的：

… truncated at 40 of 300 by limit=40 — raise limit up to 200, or narrow with types/where/ids/depth. max_chars is not the constraint here.

而当那根杠杆已经顶到天花板时，它会这么说，而不是再让你去调高，因为已经没什么可调了。

在实时画布上（panel_query_graph），同一次读取由面板自己那份引擎执行，它还没跟上那套措辞。如果那里的说明点名了一个参数，调高它却什么都没变，先试试另一根，再下结论说工具坏了。

智能体本该读自己的说明并自己重试。它没这么做时，你就是后备，而这句话就是：

被截断了 —— 读那条说明，重试同一个查询，把它们点名的那个上限调高。

上限在哪里

这些是两个按预算读节点图的工具的数字 —— panel_query_graph（实时画布）和 get_workflow 配合 action: "query"（已保存的文件）：

参数	默认	你最多能要到
`max_chars`	12000	60000
`limit`（列出的节点）	40	200

在这两个工具上，要过天花板会被当成无效参数拒绝，而不是悄悄向下取整，所以智能体立刻知道并能自己纠正。这些数字也不是通用的：另外几个工具也收 max_chars，并设自己的天花板，写在那个工具自己的描述里。

范围比预算更管用

调高天花板是第二件该试的事，不是第一件。在一张 600 节点的工作流上，更大的预算多半只是给你更多错的节点，把答案埋进几百个无关的里面，即使技术上装得下，回复也会变差。先收窄，用任何自然的词：

你说	它收到哪
「只看节点 42 和 43。」	只有那些 id
「采样器吃进了什么？」	一个节点的上游一侧
「……只往回两跳。」	从那里算起的有界距离
「这里每种节点类型有多少？」	计数而不是列表

然后，如果还是被截断，再放宽。

当它说不

工具拒绝通常不是缺陷。大多数拒绝是护栏开火了，因为这次调用会做一件你没要求的事。

「它拒绝了，我不知道为什么」

你会看到白话，而不是堆栈跟踪 —— 点名它不肯做什么、改做什么。把它读成智能体在小心，而不是卡住了。常见的诚实拒绝：

它分不清你说的是哪条工作流。 打开了不止一个标签页，或节点图还没有已保存的身份。保存它，或说出是哪一个。
它会覆盖某些东西。 要一个新文件名，它就会继续。
那东西确实不在。 模型文件、节点包、正在跑的服务器。

如果一次拒绝读起来像胡话而不是谨慎，那就值得报告 —— 让智能体去提交，它会替你附上你的环境细节。

「这个面板太旧了」

最常见、而且有真正修复的拒绝。读起来大致像：

This ComfyUI-MCP panel is too old for ”…” — update the ComfyUI-MCP panel, then reconnect.

侧边栏面板和这个服务器是分开出货的两块，所以一块可以落后于另一块。服务器要的东西，已安装的面板没法安全做到时，它会拒绝而不是猜 —— 一块旧面板如果没法确认命令会落到哪条工作流上，就可能把你的编辑打到错误的标签页，所以在更新之前它被限制在只读。修复是三步，第三步是人们会跳过的那步：

更新面板

让智能体更新它（install_comfyui(action:'panel', panel_action:'update')），或从 ComfyUI-Manager 做，那里它列名为 comfyui-agent-panel。

重启 ComfyUI

更新自己不会重启任何东西。让智能体做，或你自己重启。

硬刷新 ComfyUI 浏览器标签页

Ctrl+Shift+R（Mac 上是 Cmd+Shift+R）。浏览器缓存了旧的面板代码，光重启甩不掉。跳过这一步，同一条消息会立刻回来，所以看起来像更新失败了，其实没有。

「没有面板已连接」

不同的问题，看起来差不多的消息。意思是外面的智能体找不到你的 ComfyUI 浏览器标签页。几乎总是下面之一：

ComfyUI 根本没在浏览器里打开 —— 打开它，看侧边栏的智能体标签页。
ComfyUI 刚重启过，或你重载了标签页。那会丢掉连接。重载 ComfyUI 标签页，它马上回来。
智能体标签页开着，但从未连接过。面板在你选一个服务商并点连接时才附着，从不在加载时附着，所以刚打开、什么都没显示的标签页是普通状态，不是故障。
面板还没装。见面板指南。

消息会帮你把这些分成两组 —— 它区分「以前连过、后来掉了」和「还什么都没连过」。它不再往下走，并且会这么说，而不是挑一个它没法观察的原因。以前连过的标签页证明面板已安装并且当时能用，所以重载 ComfyUI 标签页是第一件该试的，通常也是唯一一件；如果重载没把它带回来，就当第二组，顺着上面的检查往下走。

当它什么都不说

更难的失败是里面完全没有错误的那种。智能体不调用工具，不拒绝，也不抱怨。它只是说话：描述你的工作流大概包含什么，或提出给你写脚本。听起来很帮忙，而且它什么都没看过。三种完全不同的情况会产出同一种行为，从你坐的地方看，它们无法区分：

不在

你的客户端从没拿到工具。它们不在它交给模型的列表里，所以没什么可调用。

被挡住

你的客户端有工具，但不让模型跑它们。调用停在客户端内部。

没被要过

一切都在工作。你想要的东西住在一个从没被提起的名字下面，所以没人伸手去够。

补救指向三个不同方向，其中两个如果你猜错会主动伤人：重装已经装好的东西，或放松从来不是问题的权限。所以第一步不是去修任何东西。是先搞清楚你在哪一种。

把它们分开的两个问题

用白话问智能体：

问它能看见什么

你从 comfyui-mcp 拿到哪些工具？只列名字。

几十个名字的列表是正常且健康的 —— 那是直接面，从 0.50.0 起就是默认。三个名字 —— list_tools、describe_tool、call_tool —— 也正常且健康。那是紧凑模式，通过传入 --compact 得到，小型本地模型现在仍会自动选择。目录的其余部分离一次 list_tools 调用只有一步，所以让它跑那个，你就会看到真正的列表。两种答案都不意味着有东西被扣下。一个名字都没有，或「我没有任何 ComfyUI 工具」，只排除第三种情况，别的都不排除。它不意味着不在。权限策略可以从展示给模型的列表里扣下工具，所以一台已安装、已连接、正在工作的服务器会给出正好这个答案。这一步里，不在和被挡住无法区分，而这就是让一个用户花了好几天的那条枝 —— 他确信是接线问题。有一项检查能收窄，而这不是智能体能看见的：打开你客户端自己的 MCP 服务器列表 —— 它展示连上了哪些服务器的那个地方，和它交给模型的工具列表不是同一份。

comfyui-mcp 不在，或显示失败 → 不在。客户端一侧的接线问题，不是面板或服务器故障。它再分成两种 —— 从没接上，或一台根本握不住它们的主机 —— 下面的列表把它们分开。
它在而且已连接，模型仍然列不出任何东西 → 工具已经到了你的客户端。之后停在哪仍然开放：它们可能被权限规则从模型那里扣下，或者模型只是没能或拒绝列出它们，从这里看完全一样。不要单凭这个就开始放松权限。如果那份服务器列表还显示它从 comfyui-mcp 拿走了哪些工具，事情就定了：那里列了而模型没列，说明问题在模型，不在你的权限；那里一个都没有，说明它们在模型看见之前就被过滤了。如果你的客户端不显示那个 —— 很多都不显示 —— 这里没有任何你能拿到的东西能区分这两种，第二步机会更好，因为拒绝会用文字回来。

让它试一次，并原样回报

现在调用那个你会用来做这件没在工作的事的工具，并把回来的东西原样贴出来 —— 包括任何错误。不要绕开它。

那句话里有两个细节在干活。你会用来做这件没在工作的事的那个工具，特指这个。权限规则通常按工具写，所以另一个工具成功证明不了你在乎的那个 —— 挡住就是这样藏起来的。如果没被读的是画布，测试就必须是一次画布读取。不要绕开它。 整套失败模式就是智能体悄悄绕过障碍而不点名它，由着它自己，它会再做一次。

真实结果 —— 那个工具能用。你在第三种情况。
「被拒绝了」/「不允许」/「我需要权限」 —— 被挡住，在你的客户端内部。这一条是定论：智能体问了，被拒绝了。
「我没有那个工具」 —— 仍然是不在或被挡住。被扣下的工具和缺失的工具从模型的座位上看一模一样，所以不要单凭这个行动：把它带回第一步的服务器列表，如果那份列表也不显示按服务器的工具，那你能碰到的东西就分不开这两种，诚实的下一步是去 issue 跟踪器问，而不是开始改设置。
还是散文，仍然没有调用 —— 直问：「你调用工具了吗？如果没有，为什么没有？」 躲两次的智能体，通常是在绕开一件它没提过的事。

我们从这里能看到什么，看不到什么

当你的客户端拒绝一次工具调用时，那次调用从不离开你的客户端。什么都到不了这台服务器，所以它的日志里不会出现任何东西，我们能到达的任何地方也不会产出错误。我们检测不到挡住，也不会假装能：任何声称能告诉你「你的客户端挡住了这个」的页面或消息都会是在猜。

同一事实反过来切，而这正是误导人的那一半：安静的日志不是什么都没试过的证据。不在、被挡住、以及从没被要过，从这里看都像沉默。所以上面两个问题才是真正的诊断。它们管用，是因为它们问的是当时在场的那个参与者 —— 你的智能体 —— 让它说出试了什么，并拒绝它绕开答案的选项。

每种答案通常从哪来

被挡住 —— 你客户端自己的权限规则。 在 Claude Code 里，那是 settings.json 的 permissions 块（~/.claude/settings.json，或项目的 .claude/settings.json）； MCP 工具以带命名空间的名字出现在那里，mcp__comfyui__<tool>。一份从没提到它们的严格 allow 列表会在发送之前停住每一次调用。这就是让一个用户花了好几天的那种情况：工具看起来像在工作，恰恰因为他们在找的错误永远不会出现。 不在，而且能修 —— 从没接上。 客户端会说 MCP，但从没被告知这台服务器，或被告知了但条目是错的。这是常见的那种，改一份配置就行；见快速开始了解你的客户端期望的条目。 不在，而且修不了 —— 一台根本没有 MCP 客户端的主机。 有些智能体不说 MCP，再怎么配置也改不了这个。pi 就是一个：它有自己内置的 shell 和编辑器工具，没有 MCP 客户端，所以无论还装了什么，都交不上我们的。你选它时面板会直接说 —— 「pi 没有 ComfyUI 工具（没有 MCP）」。那一行就是答案，不是要调试的症状；修复是换一个后端。 两者都有可能 —— 夹在中间的东西。 承载你 MCP 流量的网关、代理或路由器，可能只把工具面的一部分传下去。如果目录和实际跑起来的对不上，就怀疑中间那一层。

如果原来是第三种情况

那就什么都没坏，也没人配错：一项能力存在，而你无从发现。那是我们的失败而不是你的，值得告诉我们 —— 让智能体去提交，它会替你附上你的环境。一项谁都找不到的功能，从你坐的地方看，就是一项我们没发出去的功能。

如果你跑的是小型本地模型

把整份菜单交给模型，等于它开口之前先读很多东西。在大型托管模型上这没问题。在你自己机器上跑的小型模型上，这常常是能用和不能用的差别。所以默认情况下智能体拿到的是三个工具而不是完整集合：一个浏览目录，一个查单个工具的细节，一个去跑它。它在需要的时候取需要的东西，而不是一开始把所有东西读完。你不用做任何事就能得到这个 —— 这是默认。想要的话控件在这里：

# force the small three-tool mode
npx -y comfyui-mcp --compact

# or hand the model everything at once
npx -y comfyui-mcp --full

也可以用 COMFYUI_MCP_TOOL_MODE=compact 或 COMFYUI_MCP_TOOL_MODE=full 设置。代价是第一次真正动作之前多一两轮往返，换来模型还剩思考的空间。大模型通常更喜欢 --full。哪些模型扛得住哪种，见本地 LLM。

接下来去哪

快速开始

装上它，生成你的第一张图。

侧边栏面板

ComfyUI 内的智能体，以及它能对你的画布做什么。

工具参考

每个工具，带真实调用长什么样的例子。

故障排查

当它不是拒绝，而是真的坏了。

​工具是智能体可以做的事，不是你要输入的东西

​参考页里那些 JSON 是什么？

​工具来自两个地方

侧边栏面板

外面的客户端

​一个工具，多项工作

​没有删掉任何东西

​想要不一样的结果

​两种问法

​答案被截断时

​上限在哪里

​范围比预算更管用

​当它说不

​「它拒绝了，我不知道为什么」

​「这个面板太旧了」

​「没有面板已连接」

​当它什么都不说

不在

被挡住

没被要过

​把它们分开的两个问题

​我们从这里能看到什么，看不到什么

​每种答案通常从哪来

​如果原来是第三种情况

​如果你跑的是小型本地模型

​接下来去哪

快速开始

侧边栏面板

工具参考

故障排查

工具是智能体可以做的事，不是你要输入的东西

参考页里那些 JSON 是什么？

工具来自两个地方

一个工具，多项工作

没有删掉任何东西

想要不一样的结果

两种问法

答案被截断时

上限在哪里

范围比预算更管用

当它说不

「它拒绝了，我不知道为什么」

「这个面板太旧了」

「没有面板已连接」

当它什么都不说

把它们分开的两个问题

我们从这里能看到什么，看不到什么

每种答案通常从哪来

如果原来是第三种情况

如果你跑的是小型本地模型

接下来去哪