Local Image MCP

独立社区维护的本机 ComfyUI MCP 桥接工具，服务版本 1.1.2。当前测试模型为 Qwen-Image 2.1，可通过标准 stdio MCP 宿主调用；附带一个社区 DSH profile 的注册示例。

AI 辅助编写说明：代码主要由 AI 辅助生成、修改、检查并进行自动化测试。 本项目不是 Qwen、ComfyUI 或 DeepSeek 官方产品，没有获得其赞助或背书。

许可和使用范围

桥接代码按 MIT 提供，参考/改编来源及第三方许可见 NOTICE。本仓库不分发模型、第三方程序、logo 或角色素材。

Qwen-Image 2.1 模型使用研究许可，非商用限定为研究或评估，商业使用需另行授权。 本项目的 MIT 许可不会授予模型商业使用权。请先阅读 官方模型许可和公开发布自查。本项目没有给所有生成内容作合法性或权属保证。

本机配置为 RTX 4060 Laptop 8GB、Qwen-Image 2.1 Q4_K 主体、W4A8 编码器、专用 BF16 VAE。服务使用 Node 内置模块，通过 stdio MCP 调用本机 ComfyUI。模型、ComfyUI 主程序和既有 DSH 插件文件保持原配置。

当前状态：MCP 独立调用已经实际出图，注册补丁尚未应用，DSH 聊天界面内仍待验证。 原方案采用用户手动注册，这次保留这一流程。审查详情见 REVIEW.md。

Related MCP server: ComfyMCP Local

从 GitHub 下载后开始使用

本仓库保存源代码、配置示例与测试，不包含本机配置、日志、状态、模型或生成图片。已有的本机 config.json 不受影响。

新电脑或新目录需要先安装 ComfyUI 与模型，再在项目目录中执行：

Copy-Item config.example.json config.json

修改 config.json 中的 ComfyUI 路径、模型文件名和输出目录。示例采用 E 盘安装位置；按实际安装调整。需要 Node ≥22 和 Windows PowerShell，服务本身零依赖，无需 npm install。

cordis.patch.example.yml 是通用注册模板。没有本机 cordis.patch.snippet.yml 时，安装器与体检会自动使用模板并填入当前目录的 server.mjs 绝对路径；目标用户目录来自 USERPROFILE，不再依赖 Administrator 用户名。若本机已有 snippet，它优先使用，移动项目后需同步修改其中 args。

随后按下文注册。PowerShell 命令里的本机项目路径要换成你下载到的实际目录。也可以在项目目录使用 powershell -NoProfile -ExecutionPolicy Bypass -File scripts\install-patch.ps1 -Apply。

使用的四个工具

generate 的参数：

超时通常返回 status=queued 或 running 和 prompt_id。不要因此重复调用 generate，改用 get_result 查询原任务。unknown 表示历史和队列都没找到：可能 ID 错误、历史已清除、服务重启或短暂状态变化，先检查输出目录。

任务提交后，如果查询或取图失败，错误也会保留 prompt_id，供继续查询。已结束但没有保存图片、执行错误或中断，都会明确返回失败。

文件和配置

工作流：GGUF 加载器 → 文字编码 → KSampler(euler/simple) → 专用 VAE 解码 → SaveImage。配置的三个文件名分别为：

• qwen_image_2.1-Q4_K.gguf

• qwen3vl_8b_w4a8.safetensors

• qwen_image_2.1_vae_bf16.safetensors

ComfyUI 根目录：E:\ComfyUI\ComfyUI_windows_portable。 本机地址：http://127.0.0.1:8188。 输出目录：E:\ComfyUI\ComfyUI_windows_portable\ComfyUI\output。

comfy_pre_args 放 Python 参数（本次为 -s），写在 main.py 之前；comfy_args 放 ComfyUI 参数：--windows-standalone-build --reserve-vram 1 --disable-auto-launch。 generate 可以自动启动隐藏的 ComfyUI 进程；同一 MCP 进程内的并发调用共享一次启动。MCP 退出后 ComfyUI 继续运行。

环境变量可覆盖配置，例如 QWENIMG_MODELS_UNET、QWENIMG_DEFAULTS_STEPS；数组字段须使用 JSON 数组字符串，例如 QWENIMG_COMFY_PRE_ARGS=["-s"]。补丁不设置额外环境覆盖。修改配置后重启 MCP/DSH。

注册到鲸鱼娘 DSH

1. 正常退出 DSH。

2. 打开 PowerShell，先预览：

powershell -NoProfile -ExecutionPolicy Bypass -File 'E:\aiworkplace\codexworkplace\dsh\qwen-image-mcp\scripts\install-patch.ps1'

3. 应用：

powershell -NoProfile -ExecutionPolicy Bypass -File 'E:\aiworkplace\codexworkplace\dsh\qwen-image-mcp\scripts\install-patch.ps1' -Apply

4. 双击桌面“DSH 鲸鱼娘”，让模型先调用 mcp__qwenimg__status，再生成一张 512×512 图片。超时后的同一任务应调用 get_result。

注册目标是当前用户的 %USERPROFILE%\.dsh-pack-better\profiles\desktop\cordis.patch.yml。该 profile 名称与工具命名仅用于兼容性配置；本项目不分发宿主程序或社区桌面素材。 注册块使用 command: !!js process.execPath、transport: stdio、服务名 qwenimg、调用超时 900000 毫秒。等待预算覆盖最多 180 秒启动、600 秒取图等待和 HTTP 操作。当前宿主的内置 Node 为 24.18.1，已单独验证。

脚本保留块外字节、BOM、混合换行和原有块位置，拒绝重复/残缺标记及手写 ID 冲突；写前备份一份，使用同目录临时文件原子替换并自校验。原文件不以换行结尾时，新块放到文件开头，以便移除后精确恢复原字节。

回退只移除管理块：

powershell -NoProfile -ExecutionPolicy Bypass -File 'E:\aiworkplace\codexworkplace\dsh\qwen-image-mcp\scripts\install-patch.ps1' -Remove -Apply

检查与测试

在本项目目录中执行：

& 'E:\nodejs\node.exe' server.mjs --self-test
& 'E:\nodejs\node.exe' scripts\mcp-client-test.mjs
& 'E:\nodejs\node.exe' --test scripts\regression-test.mjs
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\check.ps1 -Live -Record

前三项分别通过 162 项、34 项和 30 项。回归测试只使用本机模拟 HTTP 服务与临时文件，未调用真实 ComfyUI；安装脚本的写入测试指向临时副本。

实际出图测试必须显式执行，会消耗显卡资源，并在结束时请求释放模型：

& 'E:\nodejs\node.exe' scripts\live-test.mjs --generate

本次经真实 MCP stdio 完成自动启动、generate 短等待、get_result 取回图片与内容、status 和 free_vram，512×512、20 步成功，整轮约 43 秒（含冷启动及检查，不是纯采样时间）。见 state/review-live-test.json。

之前的单次记录：768×768 冷启动约 60 秒，1024×1024 已加载约 80 秒。更长连续任务与 DSH 界面内工具调用仍待验证；这些耗时不保证每次相同。 check.ps1 -Record 保存的是环境核对，dshToolsVerified=false；不把检查通过当成 DSH 内实测通过。

升级与排错

• 工具不出现：先检查管理块和项目路径。退出 DSH 后重新预览/应用补丁。

• 宿主更新：check.ps1 会检查内置 Node、启动器版本保护与本次核对版本；启动器拦截新版本时，按 DSH 笔记库的“启动与更新”处理。

• 模型/量化变化：改 config.json 的模型名；工作流结构变化时同步模板与 NODE_MAP。配置错误会在启动时明确报错。

• 未运行：status 只报告，不启动；generate 可自动启动。

• BUSY：等队列结束，再释放显存。

• OOM：回到 512×512、批量 1；等任务结束后释放模型，再检查其他显卡软件。

• 自动启动没有命令窗口：最近 PID 在 state/comfy.pid。不要仅凭旧 PID 结束进程，先核对可执行路径和命令行确实属于这份 ComfyUI；PID 可能复用。

HTTP 请求限制为本机 HTTP 地址，不跟随重定向；超时覆盖整个响应体，响应大小有上限。图片仅允许输出目录内的 PNG，禁止路径穿越及指向目录外的链接。提示词日志只记长度和哈希，ComfyUI 异常原文也不会复制进日志。stdout 只输出协议消息；未捕获的异常会记录事件类型并结束 MCP 服务，不继续运行未知状态。