Good Comfyui

用本地 ComfyUI 生成 AI 图像的 MCP 服务器，附带"参考图 → 复刻"工具链： 角色 tag 查询（Danbooru）、本地视觉识图（Ollama）、小番茄混淆解混淆、 Civitai LoRA 精确检索/下载/验证。

功能

工具	说明
lookup_character_tags	Danbooru 角色规范 tag 查询（camofox 浏览器，30 天缓存）
lookup_character_appearance	角色外貌特征统计（solo 图 tag 频率）
generate	Anima / Krea2 双引擎文生图，可覆盖 steps/cfg/sampler，带 reference_image 自动生成对比页
extract_image_info	PNG/JPEG 元数据解析（ComfyUI prompt/workflow、WebUI parameters）
describe_image	本地识图（Ollama qwen3-vl:8b GPU；NSFW 自动 fallback llava:7b 无审查模型）
search_lora	Civitai LoRA 精确版穷举搜索（网页搜索端点 models_v9，比 API 搜索全）
download_lora	Civitai 下载 + safetensors 头验证
lookup_lora_hash	本地文件 SHA256 → C 站 by-hash 反查精确来源
deconfuse_image	小番茄混淆（Gilbert 曲线）解混淆
list_cached_characters	已缓存角色列表

快速开始（给 Agent 的提示词）

在你的 Agent（Claude / Cursor / pi 等）的会话首条消息里粘贴：

请先阅读项目 README：https://github.com/xingxue-ux/good-comfyui-mcp
按其「安装（初始化引导）」章节主动协助我完成安装与初始化，并介绍此 MCP 的功能。

更新

• git clone 安装：进入包目录执行 git pull（升级后重启 MCP 客户端生效）
• ZIP 安装：GitHub 页面 Code → Download ZIP，解压覆盖原目录 （覆盖前备份你自己改过的 pipeline.json 和 compare/ 目录）

本包未发布到 PyPI，不支持 pip install good-comfyui-mcp； 安装方式只有 git clone 或 ZIP 下载，然后在 MCP 客户端里注册 python <包目录>/good_comfyui_mcp.py 即可（pyproject.toml 仅供本地 pip install . 元数据使用，无需执行）。

注意事项：

• 升级的是代码，模型文件（anima-base-v1.0 等）无需重下；仅当更新说明提到 模型/自定义节点变更时才需要补装
• 若你改过 pipeline.json，git pull 可能冲突——先备份再更新
• 升级后重启 MCP 客户端使新代码生效，然后调 server_info 确认环境正常

复刻经验（实战教训）

• 提示词一字不改，负面也一样：同 seed 同正面、负面不同 → 画面差异可达 MAE 8+； 复刻时负面提示词必须与元数据完全一致
• PNG 被删也能找回 seed：ComfyUI /history/{prompt_id} 保留每次运行的完整 prompt（含 seed），输出文件删除不影响追溯
• training_ 前缀 = Civitai 私有训练：training_<id>-<时间戳> 命名的 LoRA 是训练任务默认命名，未发布则公开库搜不到，属正常
• LoRA 文件名可能同名不同内容：C 站"精确版"覆盖旧文件后，旧图复刻效果会变 （by-hash 反查可确认文件版本）
• 动画师 LoRA 触发词变体：画师简称可能对应 trainedWords 变体 （如 kan2 → @kan2arin → Kanzarin），搜不到全名时试触发词

默认 LoRA（5 件套）

generate 不传 lora_text 时默认挂载 5 件套（DEFAULT_LORAS）：

LoRA	权重	用途
ushikani_kassen_lora-000013	0.3	画风
anima-darklight-style-v1-000194	0.3	朦胧氛围
anima-base-1-photo-background-v4	0.6	写实背景
RealSkin SliderV2	0.8	写实皮肤
surtr945_v1	0.8	画风

• 传 lora_text="" 显式空载；传自定义 <lora:...> 覆盖默认
• 使用默认组合前需把 5 个文件放入 models/loras/，下载信息见 examples/loras_required.json（C 站 modelId/versionId/页面链接，已 by-hash 验证精确版）： curl -L -o <文件名> "https://civitai.red/api/download/models/<versionId>?token=$CIVITAI_TOKEN"
• 其他引擎（krea2）不受影响（用 lora_list 参数）

初始化验证样例（examples/）

内置两个可立即复刻的样例（完整元数据：提示词/负面/seed/参数/LoRA）， 初始化完成后跑一遍即可验证环境是否正确：

python run_example.py            # 跑全部两个样例
python run_example.py repro_anima_00015   # 只跑一个

• examples/repro_anima_00015.json + ref_repro_anima_00015.png： 双人沙发月光夜（seed 8682388855765119，5 件套 LoRA）
• examples/repro_sofa_rose.json + ref_repro_sofa_rose.png： 沙发玫瑰写实（seed 2075224187，4 LoRA 链）

脚本复刻后与参考图逐像素对比 MAE：MAE≈0 = 环境与参考一致； 差异大（>25）说明模型/LoRA 缺失或版本不符，用 server_info 检查缺失项。

安装（初始化引导）

1. Python 依赖

pip install -r requirements.txt        # mcp、httpx、numpy、pillow

2. ComfyUI（⚠️ 先确认版本）

官方安装方式任选其一（详见 https://github.com/Comfy-Org/ComfyUI ）：

• Desktop App（官方推荐，Windows/macOS）：https://www.comfy.org/download
• Windows Portable（便携版）：官方发布页下载解压即用（自带 Python 3.13 + torch cu130）
• Manual Install：git clone https://github.com/Comfy-Org/ComfyUI → pip install -r requirements.txt → N 卡安装 pip install torch torchvision torchaudio --extra-index-url https://download.pytorch.org/whl/cu130
• comfy-cli：pip install comfy-cli && comfy install

版本检查（重要）：

• 界面左下角版本号，或仓库内 comfyui_version.py（如 v0.31.0）
• 本 MCP 要求较新版本：Anima 模型原生支持 + --enable-manager pip 包方式均需 新版（约 v0.30+，2026 年版本）；老版本（2024 年及以前）的 Manager 是 custom_nodes 克隆方式，且可能不支持 Anima
• torch 最低 2.7；Nvidia 20 系以上建议 cu130+
• 启动：python main.py --enable-manager

ComfyUI-Manager（插件管理器，新版是 pip 包不是 clone）：

cd <ComfyUI目录>
python -m pip install -r manager_requirements.txt   # 安装 comfyui_manager 包
python main.py --enable-manager                      # 启用（界面右侧 Manager 按钮）
# 更新：python -m pip install -U comfyui_manager

模型（pipeline.json 引用，Anima 管线）：

• UNET：anima-base-v1.0.safetensors（放 models/diffusion_models/，C 站 civitai.red 搜索 "Anima" 下载）
• CLIP：qwen_3_06b_base.safetensors（models/text_encoders/，type=stable_diffusion）
• VAE：qwen_image_vae.safetensors（models/vae/）
• 放大：RealESRGAN_x2plus.pth（models/upscale_models/，可选）
• 默认 5 件套 LoRA（见上表，放 models/loras/）
• 自定义节点：Anima 默认管线只用 ComfyUI 内置节点，无需任何自定义节点； LoRA 由 MCP 动态注入为标准 LoraLoader 链
• Krea2 管线（可选）：Dasiwa 等 Krea2 checkpoint + qwen3vl_4b_* CLIP， 详见 KREA2_TUNING.md

3. Ollama 识图模型（按需，可后装）

官方安装：https://ollama.com/download（Windows 安装器；Linux curl -fsSL https://ollama.com/install.sh | sh） 不需要初始化时装——首次调用 describe_image 识图时再装即可：

ollama pull qwen3-vl:8b    # 主识图模型（准确，NSFW 会拒答）
ollama pull llava:7b       # 无审查 fallback（NSFW 图识图）

server_info 会以 on_demand 提示未装项；未装时 describe_image 会提醒安装。

4. camofox-browser（Danbooru 角色查询，必需）

lookup_character_tags / lookup_character_appearance 通过 camofox-browser 的 反检测浏览器访问 Danbooru（复刻前确认角色 tag 是标准流程）。 npm 官方包（本机验证可用的是 @askjo 版，需 Node >= 20）：

npm install -g @askjo/camofox-browser
camofox-browser                   # 启动服务（默认 127.0.0.1:9377）

注：npm 上有两个同名实现——@askjo/camofox-browser（askjo/jo-inc，本 MCP 验证用） 和 camofox-browser（redf0x1/redf0x1，功能类似的不同实现）；装哪个都行， 但请保持与 README 命令一致（本包按 @askjo 版验证）。

5. 环境变量

变量	默认	说明
COMFYUI_URL	http://127.0.0.1:8188	ComfyUI 地址
PIPELINE	./pipeline.json（包内）	Anima 管线 workflow 路径
MODELS_ROOT	PIPELINE 同级 models/	ComfyUI 模型根目录（含 diffusion_models/text_encoders/vae/loras 等子目录）
CAMOFOX_URL	http://127.0.0.1:9377	camofox-browser 地址
LORA_ROOT	models/loras	LoRA 目录

5b. 可选：Civitai（civitai.red）集成

search_lora / download_lora / lookup_lora_hash 三个工具依赖 Civitai。 不配置也能用其余全部功能（生成/识图/解混淆/元数据）。

civitai.red 是 Civitai 的完整 NSFW 镜像（civitai.com 会过滤内容），账号/API 通用。

1. 注册/登录 civitai.red，获取 API token： 登录后打开 https://civitai.red/user/account → API Keys → 新建 key

2. 配置 CIVITAI_TOKEN（仅 download_lora 下载需要；搜索/反查是公开端点不需要）：

   export CIVITAI_TOKEN="你的API key"
   

3. 配置 CIVITAI_SEARCH_KEY（LoRA 穷举搜索需要，网页搜索端点 search-new.civitai.com）： 打开 civitai.red 任意页 → F12 → Network 面板 → 搜索框搜任意词 → 找到 multi-search 请求 → 复制 Authorization: Bearer xxx 里的 xxx：

   export CIVITAI_SEARCH_KEY="xxx"
   

4. 验证：

   export CIVITAI_TOKEN="..." CIVITAI_SEARCH_KEY="..."
   python lora_search.py --fresh "surtr945_v1.safetensors"
   # 返回 [EXACT] ... 即 SEARCH_KEY 生效（真实搜索）
   python lora_search.py --hash "models/loras/任意LoRA.safetensors"
   # 返回 [命中] modelId=... 即网络连通（无需 token）
   

5c. 对比页查看（可选但推荐）

generate 带 reference_image 时返回的 view_url 指向本地静态服务器 （默认 http://127.0.0.1:8899）。启动方式：

cd 本包目录 && mkdir -p compare && python -m http.server 8899 -d compare

不启动也能用全部功能，只是看不到对比页（view_url 无法访问）。

6. 自检

python -c "import good_comfyui_mcp; print('OK')"   # 模块加载
# 用 MCP 客户端调用 server_info：返回每项依赖状态 + missing[] 引导提示
#（ComfyUI/模型/自定义节点/Ollama/camofox/Civitai 配置全查）

会话开始建议先调一次 server_info——它会返回 missing 列表，按提示逐项补齐即可。

给 Agent 的初始化引导说明

用户安装本 MCP 后，Agent（模型）应主动辅助用户完成初始化：

1. 第一轮先调用 setup_guide（拿到 9 步初始化清单）和 server_info（拿到缺失项）
2. 按清单逐项引导：
   • 必需项（1-6、9）：缺失时提示用户执行对应命令，完成后重新调 server_info 验证
   • 可选项（7-8）：询问用户是否需要，不需要就跳过并说明影响
3. 直到 server_info 的 missing 只剩可选项（或用户明确不需要）→ 初始化完成，进入正常使用
4. 之后每次会话可先快速调 server_info 确认环境没变（如 ComfyUI/Ollama 重启后）

依赖清单

类型	依赖	安装方式（已查证）	必需?
Python	mcp, httpx, numpy, pillow	pip install -r requirements.txt	✅
服务	ComfyUI（127.0.0.1:8188）	Desktop App / Portable / git clone + pip（见第 2 步；需新版 v0.30+ 支持 Anima）	✅
服务	ComfyUI-Manager	pip install -r manager_requirements.txt + --enable-manager（新版是 pip 包）	✅（插件管理）
模型	anima-base-v1.0 / qwen_3_06b_base / qwen_image_vae / RealESRGAN_x2plus	civitai.red 下载放对应 models 子目录	✅
LoRA	默认 5 件套（ushikani/darklight/photo-bg/RealSkin/surtr945）	civitai.red 下载放 models/loras/（可用本 MCP search_lora）	✅（默认挂载）
节点	无（pipeline 只用 ComfyUI 内置节点）	—	✅
服务	Ollama + qwen3-vl:8b + llava:7b	ollama.com/download + ollama pull（按需，首次识图时装）	可选
服务	camofox-browser（127.0.0.1:9377）	npm install -g @askjo/camofox-browser（Node>=20，另有 redf0x1 同名实现）	✅
配置	CIVITAI_TOKEN / CIVITAI_SEARCH_KEY	civitai.red API Keys / F12 抓 multi-search Bearer	可选
服务	python -m http.server 8899 -d compare	Python 自带	可选

启动

python good_comfyui_mcp.py

MCP stdio 服务器，客户端配置示例：

{
  "mcpServers": {
    "good-comfyui-mcp": {
      "command": "python",
      "args": ["/path/to/good_comfyui_mcp.py"],
      "env": { "CIVITAI_TOKEN": "你的token" }
    }
  }
}

工具链用法

参考图 → 复刻

1. extract_image_info 解析元数据（有参数直接复刻）
2. 无元数据 → describe_image 识图（NSFW 自动走 llava:7b）
3. lookup_character_tags 确认角色 tag（首次必查）
4. 与用户确认提示词
5. generate(prompt, reference_image=原图路径) 出图（自动生成对比页）

LoRA 精确检索

python lora_search.py "surtr945_v1.safetensors"     # 穷举搜索
python lora_search.py --fresh "xxx.safetensors"      # 跳过已知表重搜
python lora_search.py --hash "models/loras/xxx.safetensors"  # SHA256 反查

搜索使用 Civitai 网页搜索端点（search-new.civitai.com/multi-search， Meilisearch models_v9 索引）——API 搜索（/api/v1/models?query=）会漏掉 部分已发布模型（publishedAt 异常的），网页端点能搜到。匹配逻辑： 完整文件名（保留 @/_/---）→ 文件名一字不差 → trainedWords 触发词 （前缀/相等，短词防误报）→ 指定 base 优先 → 有文件优先。

小番茄解混淆

python xfq_tool.py 混淆图.png --mode dec --times 1

小番茄混淆 = Gilbert 曲线 + 黄金比例偏移的像素置换，可逆、无密钥。 注意：混淆后经过 JPEG 压缩/缩放的图可能无法还原（曲线位置失配）。

文件

• good_comfyui_mcp.py — MCP 服务器主程序
• pipeline.json — Anima 管线示例 workflow（默认正负提示词为通用占位）
• lora_search.py — Civitai LoRA 精确版搜索工具
• xfq_tool.py — 小番茄混淆/解混淆工具
• lora_annotate.py — LoRA 清单标注（扫描 + KNOWN 字典人工维护）
• KREA2_TUNING.md — Krea2 引擎调参笔记（量化选型/采样参数/风格 LoRA 实测）
• LICENSE — MIT
• pyproject.toml — 包元数据（pip install . 可安装，命令 good-comfyui-mcp）

已知限制

• 识图模型：qwen3-vl:8b 会拒 NSFW，fallback llava:7b（无审查但多角色图会幻觉，建议裁剪分角色识别）
• Civitai 搜索：模型级 publishedAt 异常的模型 API 搜索搜不到（网页端点可以）， 个别模型连网页端点也不收录（只能按 ID 直达或 by-hash 反查）
• 解混淆：仅支持小番茄（Gilbert 曲线）混淆；带密钥的像素混淆（如 PicEncrypt） 无法在无密钥时还原