ComfyUI_FL-MCP

# ComfyUI FL-MCP 用于从MCP兼容的客户端控制ComfyUI的MCP服务器和浏览器桥接。 [](https://github.com/comfyanonymous/ComfyUI) [](https://www.patreon.com/Machinedelusions) ## 演示  ## 功能介绍 ComfyUI FL-MCP 将 ComfyUI 暴露为工具服务器，供 MCP 客户端（如 Claude Desktop、Cursor、Codex 等代理开发环境）使用。 它提供两条控制路径： | 路径 | 生效条件 | 最适合 | |---|---|---| | **ComfyUI REST 工具** | ComfyUI 运行在 `127.0.0.1:8188` | 模型、队列、历史记录、Manager v4、文件、诊断 | | **浏览器桥接工具** | ComfyUI 在浏览器标签页中打开并连接 FL-MCP | 当前画布 JSON、节点选择、布局、截图、前端命令 | ```mermaid flowchart LR A[MCP 客户端] --> B[后端/mcp_server.py] B --> C[ComfyUI HTTP API<br/>127.0.0.1:8188] B --> D[FL-MCP 桥接后端<br/>127.0.0.1:8000] D --> E[打开 ComfyUI 浏览器标签页] E --> F[实时画布] ``` ## 亮点 - **108 个 MCP 工具**，用于工作流检查、图表编辑、队列控制、Manager v4、模型发现、文件系统检查、自定义节点开发和诊断。 - **嵌入式 ComfyUI 桥接**，带有小型 `FL-MCP` 侧边栏面板。 - **独立 MCP 模式**，适用于仅使用 REST 的控制，无需打开浏览器标签页。 - **实时画布桥接**，用于前端操作，如读取当前图表、选择/聚焦节点、截图和布局编辑。 - **安全防护**，默认禁用破坏性/写入操作。 ## 安装 ### 手动安装 ```bash cd /path/to/ComfyUI/custom_nodes git clone https://github.com/filliptm/ComfyUI_FL-MCP.git cd ComfyUI_FL-MCP pip install -r requirements.txt ``` 重启 ComfyUI。侧边栏应显示一个 `FL-MCP` 桥接选项卡。 ### 推荐 `.env` ```bash cd /path/to/ComfyUI/custom_nodes/ComfyUI_FL-MCP cp .env.example .env ``` 默认本地设置： ```dotenv AUTO_START_BACKEND=true BACKEND_LAUNCH_MODE=subprocess WS_HOST=127.0.0.1 WS_PORT=8000 COMFYUI_SERVER_URL=http://127.0.0.1:8188 ``` ## 快速开始 1. 启动 ComfyUI。 2. 在浏览器中打开 ComfyUI。 3. 确认 `FL-MCP` 侧边栏选项卡报告后端已在线。 4. 配置 MCP 客户端以运行 `backend/mcp_server.py`。 5. 从 MCP 客户端调用 `mcp_capability_audit` 以查看可用功能。 <details> <summary><strong>Claude Desktop / Cursor 样式 MCP 配置</strong></summary> 使用与安装依赖项相同的环境中的 Python 可执行文件。 ```json { "mcpServers": { "comfyui-fl-mcp": { "command": "python", "args": [ "/path/to/ComfyUI/custom_nodes/ComfyUI_FL-MCP/backend/mcp_server.py" ], "env": { "COMFYUI_SERVER_URL": "http://127.0.0.1:8188" } } } } ``` 这启用了 REST 友好工具。仅浏览器工具在未连接实时桥接会话时返回 `requires_browser_bridge`。 </details> <details> <summary><strong>启用实时浏览器/画布工具</strong></summary> 仅浏览器工具需要连接的 ComfyUI 标签页。打开 ComfyUI，打开 `FL-MCP` 侧边栏面板，然后使用桥接显示的会话详细信息运行 MCP 服务器： ```bash FL_MCP_MODE=subprocess \ FL_MCP_SESSION_ID=<session-id-from-sidebar> \ FL_MCP_WS_URL=ws://127.0.0.1:8000/ws \ python backend/mcp_server.py ``` 使用此模式适用于以下工具： - `workflow_get_current_json` - `workflow_load_json` - `find_node` - `set_node_values` - `connect_nodes` - `modify_layout` - `take_screenshot` </details> ## 运行模式 | 模式 | 进程模型 | 启动方式 | 生命周期 | |---|---|---|---| | **嵌入式子进程** | 单独的子进程 | ComfyUI 导入此自定义节点并启动 `backend/server.py` | 与 ComfyUI 父进程绑定 | | **守护进程启动器** | 独立的守护进程 | 侧边栏启动路由启动 `mcp_daemon.py` | 可以通过启动器路由停止 | | **MCP 标准输入服务器** | MCP 客户端子进程 | MCP 客户端启动 `backend/mcp_server.py` | 与 MCP 客户端绑定 | 桥接后端**不**在 ComfyUI 的主事件循环中运行。它作为一个单独的 Python 进程运行在 `127.0.0.1:8000`。 ## 安全防护 默认情况下，启用只读工具。任何写入文件、编辑工作流、修改 Manager 状态、推送 git 提交或控制进程的操作必须显式启用。 ```dotenv FL_MCP_ENABLE_WORKFLOW_WRITES=false FL_MCP_ENABLE_CUSTOM_NODE_WRITES=false FL_MCP_ENABLE_GIT_WRITES=false FL_MCP_ENABLE_MANAGER_MUTATIONS=false FL_MCP_ENABLE_COMFY_PROCESS_CONTROL=false ``` | 防护 | 启用 | |---|---| | `FL_MCP_ENABLE_WORKFLOW_WRITES` | 画布突变、工作流加载/保存/删除、设置写入、历史记录删除 | | `FL_MCP_ENABLE_CUSTOM_NODE_WRITES` | 写入文件、应用补丁、创建自定义节点包 | | `FL_MCP_ENABLE_GIT_WRITES` | 自定义节点下的 git 提交和推送工具 | | `FL_MCP_ENABLE_MANAGER_MUTATIONS` | ComfyUI Manager 安装/更新/卸载队列操作 | | `FL_MCP_ENABLE_COMFY_PROCESS_CONTROL` | 启动、停止和重启受管理的 ComfyUI 进程 | ## 工具清单 FL-MCP 目前公开了 **108 个工具**。 <details open> <summary><strong>功能和实用工具</strong></summary> | 工具 | 功能 | |---|---| | `mcp_capability_audit` | 审计桥接、REST、Manager、资产和安全防护状态 | | `calculate_expressions` | 评估一批数学表达式，用于布局或参数规划 | | `wait` | 等待短时间，在排队工作后 | | `generate_seed` | 生成随机种子 | | `generate_float` | 生成随机浮点数 | | `generate_int` | 生成随机整数 | | `random_choice` | 从列表中选择随机项目 | | `get_system_info` | 报告操作系统、Python、路径和环境详细信息 | </details> <details> <summary><strong>实时工作流和画布工具</strong></summary> 通常需要浏览器桥接。 | 工具 | 功能 | |---|---| | `query_workflow` | 查询图表并过滤、遍历和聚合 | | `workflow_overview` | 总结当前工作流 | | `workflow_diagram` | 生成 Mermaid 工作流图表 | | `workflow_get_current_json` | 读取活动工作流为可编辑的 JSON 或 API 提示 JSON | | `workflow_load_json` | 将工作流 JSON 加载到活动画布 | | `workflow_get_tabs` | 列出打开的工作流标签页和活动标签页 | | `workflow_close_current` | 关闭活动工作流标签页 | | `workflow_duplicate_current` | 复制活动工作流标签页 | | `find_node` | 按 ID、类型或标题查找节点 | | `create_nodes` | 创建一个或多个节点 | | `remove_nodes` | 删除节点 | | `bypass_nodes` | 绕过节点 | | `unbypass_nodes` | 取消绕过节点 | | `pin_nodes` | 固定节点 | | `unpin_nodes` | 取消固定节点 | | `select_nodes` | 在 UI 中选择节点 | | `get_current_node_selection` | 读取当前选定的节点 | | `focus_on_nodes` | 将画布视图拟合到节点、选择或图表 | | `take_screenshot` | 捕获当前画布 | | `get_node_values` | 读取节点的 widget 值 | | `set_node_values` | 设置节点的 widget 值 | | `get_node_slots` | 读取详细的输入/输出槽元数据 | | `connect_nodes` | 连接两个节点 | | `connect_nodes_batch` | 连接多个节点对 | | `auto_connect_workflow` | 根据类型兼容性自动连接节点 | | `get_layout` | 读取节点位置和大小 | | `modify_layout` | 应用手动布局或自动布局 | </details> <details> <summary><strong>工作流文件和标签页</strong></summary> | 工具 | 功能 | |---|---| | `workflow_list_files` | 列出从 ComfyUI 用户数据保存的工作流文件 | | `workflow_read_file` | 读取保存的工作流 JSON | | `workflow_save_current` | 保存当前工作流 | | `workflow_rename_file` | 重命名或移动工作流文件 | | `workflow_delete_file` | 删除工作流文件 | </details> <details> <summary><strong>前端命令工具</strong></summary> | 工具 | 功能 | |---|---| | `frontend_list_commands` | 列出注册的 ComfyUI 前端命令 | | `frontend_execute_command` | 按 ID 执行前端命令 | | `frontend_list_keybindings` | 列出前端命令和按键绑定 | </details> <details> <summary><strong>队列、作业、历史记录和执行工具</strong></summary> | 工具 | 功能 | |---|---| | `queue_workflow` | 队列当前工作流 | | `cancel_workflow` | 取消当前执行 | | `enable_auto_queue` | 启用自动队列 | | `disable_auto_queue` | 禁用自动队列 | | `set_batch_count` | 设置工作流批处理计数 | | `get_queue_status` | 读取前端队列状态 | | `get_queue_status_details` | 读取详细的 ComfyUI 队列和活动执行状态 | | `delete_queue_items` | 从 ComfyUI 执行队列中删除项目 | | `comfy_jobs_list` | 列出原生 ComfyUI 作业 | | `comfy_job_get` | 读取作业按提示/作业 ID | | `get_execution_history` | 读取 ComfyUI 的队列和历史记录 | | `get_execution_details` | 读取一次运行的详细执行状态 | | `clear_error_buffer` | 清除桥接错误缓冲区 | | `comfy_history_delete` | 删除历史记录条目或清除历史记录 | </details> <details> <summary><strong>ComfyUI REST、模型、资产和文件</strong></summary> | 工具 | 功能 | |---|---| | `comfy_status` | 检查 ComfyUI 进程和 HTTP 可达性 | | `comfy_get_logs` | 读取最近的托管 ComfyUI 日志 | | `comfy_free_memory` | 卸载模型和/或释放内存 | | `comfy_settings_get` | 读取 ComfyUI 设置 | | `comfy_settings_set` | 写入 ComfyUI 设置 | | `comfy_upload_image` | 从 ComfyUI 树内部上传图像 | | `comfy_upload_mask` | 从 ComfyUI 树内部上传掩码 | | `comfy_models_list` | 列出模型文件夹或文件 | | `comfy_workflow_templates_list` | 列出或读取工作流模板 | | `comfy_global_subgraphs_list` | 列出或读取全局子图 | | `comfy_node_replacements_get` | 读取节点替换映射 | | `comfy_assets_list` | 启用资产功能时列出资产 | | `comfy_asset_get` | 读取一个资产元数据记录 | | `comfy_asset_upload` | 将 ComfyUI 根文件上传到资产 | | `comfy_assets_upload` | 资产上传的别名 | | `comfy_tags_list` | 列出资产标签 | | `comfy_list_folders` | 列出 ComfyUI 文件夹并过滤和排序 | | `comfy_read_file` | 读取 ComfyUI 文件夹内的文件 | | `comfy_search_resources` | 搜索 ComfyUI 文件 | | `extract_workflow_from_image` | 从 PNG/WebP 图像中提取工作流元数据 | | `comfy_restart` | 重启托管的 ComfyUI 进程 | </details> <details> <summary><strong>节点库和兼容性工具</strong></summary> | 工具 | 功能 | |---|---| | `node_library_search` | 搜索可用的 ComfyUI 节点类型 | | `node_library_get_details` | 读取节点类型的详细元数据 | | `node_library_find_compatible` | 查找兼容的节点类型进行连接 | </details> <details> <summary><strong>ComfyUI Manager 工具</strong></summary> | 工具 | 功能 | |---|---| | `manager_v4_status` | 报告 Manager v4 的可用性和队列状态 | | `manager_v4_queue_status` | 读取 Manager v4 队列状态 | | `manager_v4_queue_action` | 排队一个确认门控的 Manager v4 操作 | | `manager_v4_installed_packs` | 列出已安装的自定义节点包 | | `manager_v4_snapshots` | 列出 Manager 快照 | | `manager_v4_node_mappings` | 查找节点到包的映射 | | `manager_v4_external_models` | 搜索外部模型定义 | | `manager_queue_action` | 排队安装/更新/卸载/禁用操作 | | `manager_queue_status` | 读取 Manager 队列状态 | | `manager_queue_start` | 启动 Manager 工作队列 | | `manager_queue_reset` | 重置 Manager 队列 | | `manager_search_nodes` | 搜索 Manager 自定义节点包 | | `manager_get_node_mappings` | 查找哪个包提供节点类型 | | `manager_check_updates` | 检查已安装的包更新 | | `manager_search_external_models` | 搜索 Manager 外部模型 | </details> <details> <summary><strong>自定义节点开发工具</strong></summary> 所有路径都在 `ComfyUI/custom_nodes` 下。 | 工具 | 功能 | |---|---| | `custom_nodes_list_packs` | 列出已安装的自定义节点包 | | `custom_nodes_read_file` | 读取自定义节点文件的有界行范围 | | `custom_nodes_read_file_excerpt` | 读取大文件的有界摘录 | | `custom_nodes_search` | 使用 ripgrep 搜索自定义节点代码 | | `custom_nodes_write_file` | 写入完整文件 | | `custom_nodes_apply_patch` | 应用统一的差异 | | `custom_nodes_create_pack` | 创建启动自定义节点包 | | `custom_nodes_validate_pack` | 运行 Python 编译验证 | | `custom_nodes_git_status` | 显示自定义节点存储库的 git 状态 | | `custom_nodes_git_diff` | 显示 git 差异 | | `custom_nodes_git_commit` | 提交更改 | | `custom_nodes_git_push` | 推送更改 | </details> ## API 端点 当桥接后端运行在 `127.0.0.1:8000`： | 端点 | 目的 | |---|---| | `GET /health` | 健康和活动会话 | | `GET /api/config` | 浏览器客户端配置 | | `GET /api/mcp/status` | MCP 桥接状态 | | `POST /api/mcp/shutdown` | 停止守护进程后端 | | `GET /api/sessions` | 连接的浏览器/MCP WebSocket 会话 | | `WS /ws` | 浏览器/MCP 桥接 WebSocket | | `GET /api/comfy/status` | 托管的 ComfyUI 进程状态 | | `GET /api/comfy/logs` | 托管的 ComfyUI 日志 | ComfyUI 还接收自定义节点启动路由： | 路径 | 目的 | |---|---| | `GET /fl_mcp/launcher/status` | 后端启动器状态 | | `POST /fl_mcp/launcher/start` | 启动守护进程后端 | | `POST /fl_mcp/launcher/stop` | 停止守护进程后端 | ## 常见工作流 <details> <summary><strong> <strong>询问当前打开的工作流</strong></summary> 1. 在浏览器中打开 ComfyUI。 2. 确认 `FL-MCP` 侧边栏选项卡已连接。 3. 要求您的 MCP 客户端调用 `workflow_get_current_json` 或 `workflow_overview`。 </details> <details> <summary><strong>清理或压缩图表布局</strong></summary> 有用的工具： - `get_layout` - `modify_layout` - `focus_on_nodes` - `workflow_get_current_json` - `workflow_load_json` </details> <details> <summary><strong>检查自定义节点后再编辑</strong></summary> 有用的工具： - `custom_nodes_list_packs` - `custom_nodes_search` - `custom_nodes_read_file_excerpt` - `custom_nodes_git_diff` - `custom_nodes_validate_pack` 在您希望 MCP 客户端写入文件或应用补丁时，请启用 `FL_MCP_ENABLE_CUSTOM_NODE_WRITES=true`。 </details> ## 故障排除 <details> <summary><strong>浏览器工具仅显示 <code>requires_browser_bridge</code></strong></summary> 打开 ComfyUI 并确保 `FL-MCP` 侧边栏面板已连接。REST 工具可以运行，但实时图表工具需要前端桥接。 </details> <details> <summary><strong>后端未启动</strong></summary> 检查： ```bash curl http://127.0.0.1:8188/fl_mcp/launcher/status curl http://127.0.0.1:8000/health ``` 日志写入： ```text ComfyUI/custom_nodes/ComfyUI_FL-MCP/backend/logs/ ComfyUI/custom_nodes/ComfyUI_FL-MCP/logs/ ``` </details> <details> <summary><strong>写入工具已禁用</strong></summary> 这是预期的。打开 `.env` 中的最窄匹配安全防护，重启后端，运行操作，然后再次关闭。 </details> ## 可选代理技能 该存储库包含一个可选的 Codex 样式技能，位于： ```text skills/workflow-assistant/ ``` 该技能为 MCP 客户端提供基于工作流的指导，用于检查、编辑、调试、压缩、验证和排队 ComfyUI 图表。 它是可选的，不会更改 FL-MCP 服务器运行时。 通过复制或将技能文件夹符号链接到客户端技能目录来安装它。 对于 Codex： ```bash mkdir -p ~/.codex/skills ln -s /path/to/ComfyUI/custom_nodes/ComfyUI_FL-MCP/skills/workflow-assistant \ ~/.codex/skills/workflow-assistant ``` 然后启动新的客户端会话并显式调用它： ```text 使用 $workflow-assistant 检查和清理我的打开的 ComfyUI 工作流。 ``` 您仍然需要单独配置 `comfyui-fl-mcp` MCP 服务器，如快速启动中所述。 ## 开发 ```bash cd /path/to/ComfyUI/custom_nodes/ComfyUI_FL-MCP pip install -r requirements.txt pytest ``` 有用的本地检查： ```bash python -m py_compile __init__.py mcp_daemon.py backend/server.py backend/mcp_server.py for f in web/js/*.js; do node --check "$f"; done ``` ## 支持 如果这节省了您构建 ComfyUI 工作流或自定义节点的时间，请支持持续的 FL 自定义节点开发： [](https://www.patreon.com/Machinedelusions)