ComfyUI APP

中文 | English

把 ComfyUI App Mode 工作流包装成 MCP 工具，让 AI 助手可以像调用普通工具一样查询模板、执行工作流、串联多步生成，并处理图片等媒体结果。

如果有 BUG 或想要的功能，可以加群 1082160486 或提 issue。

适合什么场景

• 给 AI 暴露 ComfyUI 能力：AI 只需要填写模板参数，不需要理解节点图。
• 复用 App Mode 工作流：用 ComfyUI 前端标记输入、输出，再生成 MCP 模板。
• 批量与多步执行：一次调用可运行多个独立任务，也可把前一步输出继续交给下一步处理。
• 查询本地模型：支持让 AI 查询 checkpoints、loras、vae 等模型目录。

快速开始

1. 安装插件到 ComfyUI 的 custom_nodes 目录，并安装依赖：

   cd ComfyUI/custom_nodes
   git clone <this-repo-url> ComfyUI-APP-MCP
   cd ComfyUI-APP-MCP
   python -m pip install -r requirements.txt
   

2. 启动 ComfyUI，并确保使用支持 App Mode 的版本。

3. 打开工作流，在左上角菜单进入 App Builder。

4. 标记希望 AI 修改的内容为输入，标记保存图片等节点为输出，并把输入命名成清晰参数名。

5. 添加 Markdown Note 说明模板：

   • title：模板短标题，显示在模板列表中
   • description：模板详细说明，显示在模板详情中
   • 其他标题：作为可按需读取的模板文档

6. 在 Settings → MCP Server → Templates 点击 Create from Workflow 创建模板。

7. 在 MCP 客户端连接 http://127.0.0.1:8188/app-mcp 或 http://127.0.0.1:8189/mcp。

8. 让 AI 先调用 list_templates()，再调用 get_template()、run_template() 或 run_templates()。

工作流变更后，在设置面板对同名模板点击 Refresh。如果输入参数发生变化，提醒 AI 重新读取模板。

如果希望每次运行自动随机 seed，把 App Builder 中对应输入命名为 seed。运行时会自动填入随机值，AI 不需要传这个参数。

连接地址

入口	地址	说明
ComfyUI 代理入口	http://127.0.0.1:8188/app-mcp	通过 ComfyUI 端口访问 MCP
MCP 直接入口	http://127.0.0.1:8189/mcp	随 ComfyUI 一起启动，和上面用法一致

MCP 客户端配置示例：

{
  "mcpServers": {
    "comfyui": {
      "url": "http://127.0.0.1:8188/app-mcp"
    }
  }
}

也可以把 url 换成：

http://127.0.0.1:8189/mcp

远程访问 ComfyUI 时，使用 python main.py --listen 启动。

局域网或远程访问时，把 127.0.0.1 换成实际 ComfyUI/MCP 机器地址。更多部署方式见 独立部署与远程访问。

常用工具

工具	用途	什么时候用
list_templates()	查看可用模板	开始任务前先查有哪些能力
get_template(name)	读取模板参数、输出、文档入口	执行前确认参数怎么填
read_template_doc(name, title)	读取模板的扩展说明	description 提到更多文档时使用
run_template()	执行单个模板	文生图、图生图、放大、加密等单步任务
run_templates()	一次运行多个任务并返回每一步结果	批量生成，或生成 → 放大等多步处理
upload_image(source)	上传用户提供的新图片	图片来自用户本地、URL 或 base64 时
list_models(folder, keywords)	查询模型目录	需要选择 checkpoint、LoRA、VAE 时
get_template_result()	查询或继续等待结果	run_template 超时或异步等待时

完整参数、返回结构和示例见 工具参考。

前端管理

在 Settings → MCP Server 中可以：

• 查看 MCP 服务状态和连接地址
• 设置 run_template(wait=true) 默认等待超时
• 创建、刷新、启用、禁用、删除模板
• 扫描工作流并自动创建缺失模板
• 批量刷新已有模板
• 导出模板 zip，用于独立部署

更多说明见 工具参考：前端管理。

文档导航

文档	内容
工具参考	MCP 工具参数、返回格式、模板串联、上传图片、模型查询
独立部署与远程访问	环境变量、独立配置、媒体代理、客户端连接
故障排查	模板为空、输出为空、图片输入、远程访问、日志
开发说明	代码结构、测试建议、开发命令
文档索引	中英文文档入口

最常见问题

模板列表为空

确保工作流已通过 ComfyUI 的 Save 保存到服务器，而不是只用 Export 导出到本地。

图片输入不生效

用户提供的新图片先用 upload_image() 上传，再把返回的 name 填入模板参数。模板生成的图片交给 AI 串联即可，不需要手动上传。

创建模板时找不到工作流

确认 ComfyUI 是否运行在 8188 端口。插件默认通过 COMFYUI_URL=http://127.0.0.1:8188 读取工作流；如果你的 ComfyUI 端口不是 8188，启动前设置：

COMFYUI_URL=http://127.0.0.1:<你的端口>

接入 AstrBot 等平台后图片发不出来

确认 AI 调用平台发送工具时参数类型正确。常见错误是把图片 URL 填到 path 这类本地文件路径参数里；如果平台工具区分 url、image_url、file、path，应按工具要求传对应字段。

更多排查方式见 故障排查。