Skip to content
Back to search

ComfyUI-AnimaTool

AI Tool Use API for Anima anime/illustration image generation. Supports MCP Server, HTTP API, and CLI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/moeblack--comfyui-animatool/badge.svg)](/listings/moeblack--comfyui-animatool)

HTML

<a href="/listings/moeblack--comfyui-animatool"><img src="/api/listings/moeblack--comfyui-animatool/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Cherry Studio 用户

如果你使用 Cherry Studio 作为 MCP 客户端,需要安装我们的预览版才能正确显示 MCP 返回的图片:

1. 下载 [Cherry Studio v1.7.17-preview](https://github.com/Moeblack/cherry-studio/releases/tag/v1.7.17-preview)(安装版或便携版均可) 2. 安装后按下方「方式 1:MCP Server」配置即可 3. 生成的图片会直接显示在聊天窗口中

> 官方版 Cherry Studio 尚未合并此修复,使用官方版会导致图片显示为 base64 乱码,且多轮出图后会严重卡顿。 > v1.7.17-preview 基于上游 v1.7.17,修复了出图后内存膨胀和 UI 冻结的问题([详情](https://github.com/CherryHQ/cherry-studio/pull/12766))。

Method 1: ComfyUI Manager (Recommended)

1. 打开 ComfyUI Manager 2. 搜索 "Anima Tool" 3. 点击 Install 4. 重启 ComfyUI

Method 2: Manual Install

cd ComfyUI/custom_nodes
git clone https://github.com/Moeblack/ComfyUI-AnimaTool.git
pip install -r ComfyUI-AnimaTool/requirements.txt

Prerequisites

确保以下模型文件已放置到 ComfyUI 对应目录:

| 文件 | 路径 | 说明 | |------|------|------| | `anima-preview.safetensors` | `models/diffusion_models/` | Anima UNET | | `qwen_3_06b_base.safetensors` | `models/text_encoders/` | Qwen3 CLIP | | `qwen_image_vae.safetensors` | `models/vae/` | VAE |

模型下载:[circlestone-labs/Anima on Hugging Face](https://huggingface.co/circlestone-labs/Anima)

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 622 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # ComfyUI-AnimaTool
  2. > [!NOTE]
  3. > **今日更新**
  4. > - 🎰 **十连抽功能** — 支持 `repeat` / `batch_size`,一次出多张不是梦
  5. > - 🔄 **更换卡池功能** — 可以切换 UNET / CLIP / VAE 模型了,试试新卡池
  6. > - 📋 **寻访记录功能** — 查看历史生成记录,支持 reroll 重新抽卡
  7. >
  8. > ✅ **云端/远程连接更简单** — 新增 `uvx` 免安装模式,一行配置连接远程 ComfyUI,无需本地环境
  9. > ✅ **酒馆 MCP 客户端已发布** — [SillyTavern MCP Client](https://github.com/Moeblack/sillytavern-mcp-client),支持 stdio + Streamable HTTP 传输
  10. >
  11. > ✅ **工具调用体验修复** — [Tool Use Fix](https://github.com/Moeblack/sillytavern-tooluse-fix),合并碎片消息、图片直接显示、Swipe 代理
  12. > [!TIP]
  13. > **Cherry Studio 现已支持 MCP 图片显示!**
  14. > 我们提交的 PR 已修复 Cherry Studio 对 MCP `ImageContent` 的处理。在官方合并之前,你可以使用预览版体验完整的 MCP 图片功能:
  15. > **下载预览版** → [Cherry Studio v1.7.17-preview](https://github.com/Moeblack/cherry-studio/releases/tag/v1.7.17-preview)
  16. > 包含以下修复:
  17. > - 支持按助手单独配置是否将 MCP 工具图片发送给模型
  18. > - 修复 OpenAI 兼容提供商的 base64 图片数据处理
  19. > - 修复 Gemini 的 MCP 多模态工具结果转换
  20. > - **性能修复 v2**:解决多轮出图后严重卡顿问题 — IPC 排除大 slice + base64 就地 strip(修复了 v1.7.16-preview2 中 Zod safeParse 克隆导致 strip 无效的问题)— [上游 PR #12766](https://github.com/CherryHQ/cherry-studio/pull/12766)
  21. <p align="center">
  22. <img src="assets/hero.webp" alt="ComfyUI-AnimaTool Demo" width="100%">
  23. </p>
  24. <p align="center">
  25. <b>让 AI Agent 直接生成二次元图片,原生显示在聊天窗口</b>
  26. </p>
  27. <p align="center">
  28. Cursor / Claude / Gemini / OpenAI → MCP / HTTP API → ComfyUI → Anima 模型
  29. </p>
  30. ---
  31. ![Screenshot](assets/screenshot.webp)
  32. ## Documentation
  33. - [📖 Wiki & Prompt Guide](https://github.com/Moeblack/ComfyUI-AnimaTool/wiki) - 详细的提示词指南、安装教程和 API 文档。
  34. - [🤖 Cursor Skill](CURSOR_SKILL.md) - **Cursor / Windsurf 用户必读**!将此文件内容作为 Agent Skill,让 AI 学会如何写高质量提示词。
  35. ## Features
  36. - **MCP Server**:图片原生显示在 Cursor/Claude 聊天窗口
  37. - **HTTP API**:随 ComfyUI 启动,无需额外服务
  38. - **结构化提示词**:按 Anima 规范自动拼接
  39. - **多长宽比支持**:21:9 到 9:21(共 14 种预设)
  40. - **Reroll / 历史记录**:支持基于历史记录重新生成,可覆盖部分参数(换画师、加 LoRA 等)
  41. - **批量生成**:`repeat` 参数提交多次独立任务(queue 模式),`batch_size` 在单任务内生成多张
  42. ---
  43. ## Related Projects
  44. ### SillyTavern 全家桶
  45. 在 SillyTavern(酒馆)中使用 AnimaTool 生成图片?推荐安装以下配套插件:
  46. | 项目 | 说明 |
  47. |------|------|
  48. | [SillyTavern MCP Client](https://github.com/Moeblack/sillytavern-mcp-client) | 酒馆 MCP 客户端,连接 AnimaTool 等 MCP Server,支持 stdio + Streamable HTTP |
  49. | [SillyTavern Tool Use Fix](https://github.com/Moeblack/sillytavern-tooluse-fix) | 工具调用体验修复,合并碎片消息、图片直接显示在对话中 |
  50. ```
  51. ComfyUI-AnimaTool (本项目,MCP Server)
  52. ↕ MCP 协议 (stdio / streamable-http)
  53. SillyTavern MCP Client (连接 + 工具注册)
  54. ↕ SillyTavern Tool Calling
  55. Tool Use Fix (合并显示 + 体验优化)
  56. ```
  57. ### AnimaLoraToolkit - LoRA 训练工具
  58. 如果你想训练自己的 LoRA/LoKr 来搭配 Anima 使用,推荐使用 **[AnimaLoraToolkit](https://github.com/Moeblack/AnimaLoraToolkit)**:
  59. - **YAML 配置文件** - 通过 `--config` 加载,命令行参数可覆盖
  60. - **LoRA / LoKr 双模式** - 标准 LoRA 和 LyCORIS LoKr
  61. - **ComfyUI 兼容** - 输出的 safetensors 可直接在本工具中使用
  62. - **JSON Caption 支持** - 结构化标签,分类 shuffle
  63. - **实时训练监控** - Web 界面显示 loss 曲线和采样图
  64. - **Checkpoint 恢复** - 保存完整训练状态,支持断点续训
  65. 训练完成后,将 LoRA 放入 `ComfyUI/models/loras/` 目录,即可通过本工具的 `loras` 参数加载使用。
  66. #### 示例:Cosmic Princess Kaguya LoKr
  67. 使用 AnimaLoraToolkit 训练的画风+角色 LoKr,还原 Netflix 动画电影《超时空辉耀姬!》的 4K 剧场版画风:
  68. - **下载**:[Civitai](https://civitai.com/models/2366705)
  69. - **触发词**:`@spacetime kaguya`(画风)、`cosmic princess kaguya`(作品)
  70. - **推荐权重**:0.8 - 1.0
  71. ---
  72. ## Installation
  73. ### Cherry Studio 用户
  74. 如果你使用 Cherry Studio 作为 MCP 客户端,需要安装我们的预览版才能正确显示 MCP 返回的图片:
  75. 1. 下载 [Cherry Studio v1.7.17-preview](https://github.com/Moeblack/cherry-studio/releases/tag/v1.7.17-preview)(安装版或便携版均可)
  76. 2. 安装后按下方「方式 1:MCP Server」配置即可
  77. 3. 生成的图片会直接显示在聊天窗口中
  78. > 官方版 Cherry Studio 尚未合并此修复,使用官方版会导致图片显示为 base64 乱码,且多轮出图后会严重卡顿。
  79. > v1.7.17-preview 基于上游 v1.7.17,修复了出图后内存膨胀和 UI 冻结的问题([详情](https://github.com/CherryHQ/cherry-studio/pull/12766))。
  80. ### Method 1: ComfyUI Manager (Recommended)
  81. 1. 打开 ComfyUI Manager
  82. 2. 搜索 "Anima Tool"
  83. 3. 点击 Install
  84. 4. 重启 ComfyUI
  85. ### Method 2: Manual Install
  86. ```bash
  87. cd ComfyUI/custom_nodes
  88. git clone https://github.com/Moeblack/ComfyUI-AnimaTool.git
  89. pip install -r ComfyUI-AnimaTool/requirements.txt
  90. ```
  91. ### Prerequisites
  92. 确保以下模型文件已放置到 ComfyUI 对应目录:
  93. | 文件 | 路径 | 说明 |
  94. |------|------|------|
  95. | `anima-preview.safetensors` | `models/diffusion_models/` | Anima UNET |
  96. | `qwen_3_06b_base.safetensors` | `models/text_encoders/` | Qwen3 CLIP |
  97. | `qwen_image_vae.safetensors` | `models/vae/` | VAE |
  98. 模型下载:[circlestone-labs/Anima on Hugging Face](https://huggingface.co/circlestone-labs/Anima)
  99. ---
  100. ## Usage
  101. ### 方式 0:独立 MCP(推荐:云端/远程 ComfyUI,或不想装到 custom_nodes)
  102. 如果你只想连接一台正在运行的 ComfyUI(本机或云端),并且不想把本仓库放进 `ComfyUI/custom_nodes/`,可以使用独立 PyPI 包 **[`comfyui-animatool`](https://github.com/Moeblack/animatool-mcp)**(安装后使用命令 `animatool-mcp`)(仅通过 ComfyUI 标准 API:`/prompt`、`/history/<id>`、`/view?...` 工作)。
  103. #### 安装
  104. **方式一:使用 uvx (推荐,无需安装)**
  105. 无需手动安装 Python 包,直接在 Cursor 配置中使用 `uvx` 运行(需安装 [uv](https://github.com/astral-sh/uv)):
  106. *(配置见下方 JSON)*
  107. **方式二:使用 pip**
  108. ```bash
  109. pip install comfyui-animatool
  110. ```
  111. **方式三:源码安装 (开发用)**
  112. ```bash
  113. pip install -e ./animatool-mcp
  114. ```
  115. #### 配置 Cursor
  116. 在项目根目录创建 `.cursor/mcp.json`(以 `uvx` 为例):
  117. ```json
  118. {
  119. "mcpServers": {
  120. "anima-tool": {
  121. "command": "uvx",
  122. "args": ["--from", "comfyui-animatool", "animatool-mcp"],
  123. "env": {
  124. "COMFYUI_URL": "http://127.0.0.1:8188",
  125. "ANIMATOOL_CHECK_MODELS": "false"
  126. }
  127. }
  128. }
  129. }
  130. ```
  131. #### 云端鉴权(可选)
  132. 如果云端 ComfyUI 需要鉴权(反代/VPN/网关等),可额外设置:
  133. - `ANIMATOOL_BEARER_TOKEN`
  134. - 或 `ANIMATOOL_HEADERS_JSON`(自定义 Header JSON 字符串)
  135. > 该方式**不依赖**安装本 custom node;只要 `COMFYUI_URL` 可访问即可。
  136. ---
  137. ### 方式 1:MCP Server(推荐,原生图片显示)
  138. #### 配置 Cursor
  139. 在项目根目录创建 `.cursor/mcp.json`:
  140. ```json
  141. {
  142. "mcpServers": {
  143. "anima-tool": {
  144. "command": "<PATH_TO_PYTHON>",
  145. "args": ["<PATH_TO>/ComfyUI-AnimaTool/servers/mcp_server.py"]
  146. }
  147. }
  148. }
  149. ```
  150. **示例(Windows)**:
  151. ```json
  152. {
  153. "mcpServers": {
  154. "anima-tool": {
  155. "command": "C:\\ComfyUI\\.venv\\Scripts\\python.exe",
  156. "args": ["C:\\ComfyUI\\custom_nodes\\ComfyUI-AnimaTool\\servers\\mcp_server.py"]
  157. }
  158. }
  159. }
  160. ```
  161. #### 安装 MCP 依赖
  162. ```bash
  163. pip install mcp
  164. ```
  165. #### 使用
  166. 1. 确保 ComfyUI 运行在 `http://127.0.0.1:8188`
  167. 2. 重启 Cursor 加载 MCP Server
  168. 3. 直接让 AI 生成图片:
  169. > 画一个穿白裙的少女在花园里,竖屏 9:16,safe
  170. 图片会**原生显示**在聊天窗口中。
  171. ---
  172. ### 方式 2:ComfyUI 内置 HTTP API
  173. 启动 ComfyUI 后,以下路由自动注册:
  174. | 路由 | 方法 | 说明 |
  175. |------|------|------|
  176. | `/anima/health` | GET | 健康检查 |
  177. | `/anima/schema` | GET | Tool Schema |
  178. | `/anima/knowledge` | GET | 专家知识 |
  179. | `/anima/generate` | POST | 执行生成(支持 `repeat` 批量) |
  180. | `/anima/history` | GET | 查看最近生成历史 |
  181. | `/anima/reroll` | POST | 基于历史记录重新生成 |
  182. #### 调用示例
  183. **PowerShell**:
  184. ```powershell
  185. $body = @{
  186. aspect_ratio = "3:4"
  187. quality_meta_year_safe = "masterpiece, best quality, newest, year 2024, safe"
  188. count = "1girl"
  189. artist = "@fkey, @jima"
  190. tags = "upper body, smile, white dress"
  191. neg = "worst quality, low quality, blurry, bad hands, nsfw"
  192. } | ConvertTo-Json -Depth 10
  193. Invoke-RestMethod -Uri "http://127.0.0.1:8188/anima/generate" -Method Post -Body $body -ContentType "application/json"
  194. ```
  195. **curl**:
  196. ```bash
  197. curl -X POST http://127.0.0.1:8188/anima/generate \
  198. -H "Content-Type: application/json" \
  199. -d '{"aspect_ratio":"3:4","quality_meta_year_safe":"masterpiece, best quality, newest, year 2024, safe","count":"1girl","artist":"@fkey, @jima","tags":"upper body, smile, white dress","neg":"worst quality, low quality, blurry, bad hands, nsfw"}'
  200. ```
  201. ---
  202. ### 方式 3:独立 FastAPI Server
  203. ```bash
  204. cd ComfyUI-AnimaTool
  205. pip install fastapi uvicorn
  206. python -m servers.http_server
  207. ```
  208. 访问 `http://127.0.0.1:8000/docs` 查看 Swagger UI。
  209. ---
  210. ## Parameters
  211. ### Required
  212. | 参数 | 类型 | 说明 |
  213. |------|------|------|
  214. | `quality_meta_year_safe` | string | 质量/年份/安全标签(必须包含 safe/sensitive/nsfw/explicit) |
  215. | `count` | string | 人数(`1girl`, `2girls`, `1boy`) |
  216. | `artist` | string | 画师,**必须带 `@`**(如 `@fkey, @jima`) |
  217. | `tags` | string | Danbooru 标签 |
  218. | `neg` | string | 负面提示词 |
  219. ### Optional
  220. | 参数 | 类型 | 默认值 | 说明 |
  221. |------|------|--------|------|
  222. | `aspect_ratio` | string | - | 长宽比(自动计算分辨率) |
  223. | `width` / `height` | int | - | 直接指定分辨率 |
  224. | `character` | string | `""` | 角色名 |
  225. | `series` | string | `""` | 作品名 |
  226. | `appearance` | string | `""` | 外观描述 |
  227. | `style` | string | `""` | 画风 |
  228. | `environment` | string | `""` | 环境/光影 |
  229. | `steps` | int | 25 | 步数 |
  230. | `cfg` | float | 4.5 | CFG |
  231. | `seed` | int | 随机 | 种子 |
  232. | `sampler_name` | string | `er_sde` | 采样器 |
  233. | `repeat` | int | 1 | 提交几次独立生成任务(queue 模式,每次独立随机 seed)。总张数 = repeat × batch_size |
  234. | `batch_size` | int | 1 | 单次任务内生成几张(latent batch 模式,更吃显存) |
  235. | `loras` | array | `[]` | 可选:追加 LoRA(仅 UNET)。`name` 为 `ComfyUI/models/loras/` 下的相对路径(可含子目录),示例:`[{"name":"_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors","weight":0.8}]` |
  236. ### Supported Aspect Ratios
  237. ```
  238. 横屏: 21:9, 2:1, 16:9, 16:10, 5:3, 3:2, 4:3
  239. 方形: 1:1
  240. 竖屏: 3:4, 2:3, 3:5, 10:16, 9:16, 1:2, 9:21
  241. ```
  242. ---
  243. ### LoRA(可选)
  244. > 当前版本会在 **UNETLoader → KSampler(model)** 之间链式注入 `LoraLoaderModelOnly`,因此**只对 UNET 生效**(不会改 CLIP)。
  245. #### 1)把 LoRA 放到 ComfyUI 的 loras 目录
  246. 你的 LoRA 路径(示例):
  247. - `G:\\AIGC\\ComfyUICommon\\models\\loras\\_Anima\\cosmic_kaguya_lokr_epoch4_comfyui.safetensors`
  248. 对应请求里 `loras[i].name` 应写为(相对 `models/loras/`):
  249. - 推荐写法:`_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors`
  250. > 说明:ComfyUI 侧实际会校验 `lora_name` 是否在 `GET /models/loras` 的返回列表里。
  251. > - Windows 环境下该列表通常是反斜杠路径(例如 `_Anima\\cosmic_kaguya_lokr_epoch4_comfyui.safetensors`)
  252. > - **本项目会根据 `/models/loras` 返回值自动规范化分隔符**(你用 `/` 或 `\\` 都可以),但如果你直接在 ComfyUI 里手工填 `lora_name`,请务必复制接口返回值。
  253. #### 2)生成时传入 loras 参数
  254. 可直接参考本仓库示例:[`examples/requests/generate_with_cosmic_kaguya_lora.json`](examples/requests/generate_with_cosmic_kaguya_lora.json)
  255. ```json
  256. {
  257. "aspect_ratio": "3:4",
  258. "quality_meta_year_safe": "newest, year 2024, safe",
  259. "count": "1girl",
  260. "character": "kaguya",
  261. "series": "cosmic princess kaguya",
  262. "artist": "@spacetime kaguya",
  263. "appearance": "long hair, black hair, purple eyes",
  264. "tags": "school uniform, smile, standing, looking at viewer",
  265. "environment": "classroom, window, sunlight",
  266. "nltags": "A cheerful girl stands by the window.",
  267. "neg": "worst quality, low quality, blurry, bad hands, nsfw",
  268. "loras": [
  269. {
  270. "name": "_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors",
  271. "weight": 0.9
  272. }
  273. ]
  274. }
  275. ```
  276. #### 3)(可选)为 LoRA 写 sidecar 元数据,让 MCP 的 list 工具可见
  277. 为了避免把整个 `loras` 目录无差别暴露给 MCP 客户端,本项目在 `list_anima_models(model_type="loras")` 时**强制只返回存在同名 `.json` sidecar 元数据文件的 LoRA**。
  278. - LoRA 文件:`ComfyUI/models/loras/_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors`
  279. - sidecar:`ComfyUI/models/loras/_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors.json`
  280. 示例 sidecar 文件可参考:
  281. - [`examples/loras/_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors.json`](examples/loras/_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors.json)
  282. > sidecar JSON 的字段结构完全自定义,本项目只要求其为合法 JSON。
  283. > 注意:要让 MCP 服务端读取该 sidecar,你还需要设置 `COMFYUI_MODELS_DIR` 指向本机的 **models 根目录**(例如 `C:\\ComfyUI\\models`;你的示例则是 `G:\\AIGC\\ComfyUICommon\\models`)。远程 ComfyUI 场景通常无法读取远程文件系统,因此只支持“直接使用 loras 参数”,不支持 list。
  284. ---
  285. ## Important Rules
  286. 1. **画师必须带 `@`**:如 `@fkey, @jima`,否则几乎无效
  287. 2. **必须明确安全标签**:`safe` / `sensitive` / `nsfw` / `explicit`
  288. 3. **推荐画师组合**:`@fkey, @jima`(效果稳定)
  289. 4. **分辨率约 1MP**:Anima preview 版本更稳定
  290. 5. **提示词不分行**:单行逗号连接
  291. ---
  292. ## Directory Structure
  293. ```
  294. ComfyUI-AnimaTool/
  295. ├── __init__.py # ComfyUI extension(注册 /anima/* 路由)
  296. ├── executor/ # 核心执行器
  297. │ ├── anima_executor.py
  298. │ ├── config.py
  299. │ ├── history.py # 生成历史管理器(内存 + JSONL 持久化)
  300. │ └── workflow_template.json
  301. ├── knowledge/ # 专家知识库
  302. │ ├── anima_expert.md
  303. │ ├── artist_list.md
  304. │ └── prompt_examples.md
  305. ├── schemas/ # Tool Schema
  306. │ └── tool_schema_universal.json
  307. ├── servers/
  308. │ ├── mcp_server.py # MCP Server(原生图片返回)
  309. │ ├── http_server.py # 独立 FastAPI
  310. │ └── cli.py # 命令行工具
  311. ├── assets/ # 截图等资源
  312. ├── outputs/ # 生成的图片(gitignore)
  313. ├── README.md
  314. ├── LICENSE
  315. ├── CHANGELOG.md
  316. ├── pyproject.toml
  317. └── requirements.txt
  318. ```
  319. ---
  320. ## Configuration
  321. ### 环境变量(推荐)
  322. 所有配置都可以通过环境变量覆盖,无需修改代码:
  323. #### 基础配置
  324. | 环境变量 | 默认值 | 说明 |
  325. |----------|--------|------|
  326. | `COMFYUI_URL` | `http://127.0.0.1:8188` | ComfyUI 服务地址 |
  327. | `ANIMATOOL_TIMEOUT` | `600` | 生成超时(秒) |
  328. | `ANIMATOOL_DOWNLOAD_IMAGES` | `true` | 是否保存图片到本地 |
  329. | `ANIMATOOL_OUTPUT_DIR` | `./outputs` | 图片输出目录 |
  330. | `ANIMATOOL_TARGET_MP` | `1.0` | 目标像素数(MP) |
  331. | `ANIMATOOL_ROUND_TO` | `16` | 分辨率对齐倍数 |
  332. #### 模型配置
  333. | 环境变量 | 默认值 | 说明 |
  334. |----------|--------|------|
  335. | `COMFYUI_MODELS_DIR` | *(未设置)* | ComfyUI models 目录路径,用于模型预检查;同时也用于 **LoRA sidecar 元数据读取**(`list_anima_models(model_type="loras")`) |
  336. | `ANIMATOOL_UNET_NAME` | `anima-preview.safetensors` | UNET 模型文件名 |
  337. | `ANIMATOOL_CLIP_NAME` | `qwen_3_06b_base.safetensors` | CLIP 模型文件名 |
  338. | `ANIMATOOL_VAE_NAME` | `qwen_image_vae.safetensors` | VAE 模型文件名 |
  339. | `ANIMATOOL_CHECK_MODELS` | `true` | 是否启用模型预检查 |
  340. ### 在 Cursor MCP 配置中设置环境变量
  341. ```json
  342. {
  343. "mcpServers": {
  344. "anima-tool": {
  345. "command": "C:\\ComfyUI\\.venv\\Scripts\\python.exe",
  346. "args": ["C:\\ComfyUI\\custom_nodes\\ComfyUI-AnimaTool\\servers\\mcp_server.py"],
  347. "env": {
  348. "COMFYUI_URL": "http://127.0.0.1:8188",
  349. "COMFYUI_MODELS_DIR": "C:\\ComfyUI\\models"
  350. }
  351. }
  352. }
  353. }
  354. ```
  355. ### 模型预检查
  356. 设置 `COMFYUI_MODELS_DIR` 后,生成前会自动检查模型文件是否存在:
  357. ```json
  358. "env": {
  359. "COMFYUI_MODELS_DIR": "C:\\ComfyUI\\models"
  360. }
  361. ```
  362. 如果缺少模型文件,会给出友好提示:
  363. ```
  364. 缺少以下模型文件:
  365. - unet: diffusion_models/anima-preview.safetensors
  366. - clip: text_encoders/qwen_3_06b_base.safetensors
  367. 请从 HuggingFace 下载:https://huggingface.co/circlestone-labs/Anima
  368. 并放置到 ComfyUI/models/ 对应子目录
  369. ```
  370. **远程 ComfyUI 场景**:如果不设置 `COMFYUI_MODELS_DIR`,则跳过预检查(因为无法访问远程文件系统)。
  371. ### 远程/Docker ComfyUI 配置
  372. 如果 ComfyUI 不在本机运行:
  373. **局域网其他电脑**:
  374. ```bash
  375. export COMFYUI_URL=http://192.168.1.100:8188
  376. ```
  377. **Docker 容器访问宿主机**:
  378. ```bash
  379. export COMFYUI_URL=http://host.docker.internal:8188
  380. ```
  381. **WSL 访问 Windows**:
  382. ```bash
  383. export COMFYUI_URL=http://$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):8188
  384. ```
  385. ---
  386. ## Troubleshooting
  387. ### 错误:无法连接到 ComfyUI
  388. **症状**:`Connection refused` 或 `无法连接到 ComfyUI`
  389. **排查步骤**:
  390. 1. 确认 ComfyUI 已启动:浏览器访问 `http://127.0.0.1:8188`
  391. 2. 确认端口正确:默认 8188,如果改过需要设置 `COMFYUI_URL`
  392. 3. 确认防火墙未阻止(Windows Defender / 企业防火墙)
  393. 4. 如果 ComfyUI 在远程/Docker,设置正确的 `COMFYUI_URL`
  394. ### 错误:H,W should be divisible by spatial_patch_size
  395. **症状**:`H,W (xxx, xxx) should be divisible by spatial_patch_size 2`
  396. **原因**:分辨率不是 16 的倍数
  397. **解决**:
  398. - 使用预设的 `aspect_ratio`(如 `16:9`、`9:16`、`1:1`)
  399. - 如果手动指定 `width`/`height`,确保是 16 的倍数(如 512、768、1024)
  400. ### 错误:模型文件不存在
  401. **症状**:ComfyUI 控制台报 `FileNotFoundError` 或 `Model not found`
  402. **解决**:确认以下文件存在:
  403. | 文件 | 位置 |
  404. |------|------|
  405. | `anima-preview.safetensors` | `ComfyUI/models/diffusion_models/` |
  406. | `qwen_3_06b_base.safetensors` | `ComfyUI/models/text_encoders/` |
  407. | `qwen_image_vae.safetensors` | `ComfyUI/models/vae/` |
  408. 下载地址:[circlestone-labs/Anima](https://huggingface.co/circlestone-labs/Anima)
  409. ### MCP Server 没加载?
  410. 1. **检查状态**:Cursor Settings → MCP → anima-tool 应显示绿色
  411. 2. **查看日志**:点击 "Show Output" 查看错误
  412. 3. **确认路径**:Python 和脚本路径必须是**绝对路径**
  413. 4. **确认依赖**:`pip install mcp`(使用 ComfyUI 的 Python 环境)
  414. 5. **重启 Cursor**:修改配置后必须重启
  415. ### 生成超时?
  416. **症状**:等待很久后报 `TimeoutError`
  417. **可能原因**:
  418. - ComfyUI 正在加载模型(首次生成较慢)
  419. - GPU 显存不足导致处理缓慢
  420. - 步数 `steps` 设置过高
  421. **解决**:
  422. - 增加超时时间:`export ANIMATOOL_TIMEOUT=1200`
  423. - 降低步数:`steps: 25`(默认值)
  424. - 检查 ComfyUI 控制台是否有错误
  425. ### API 调用卡住?
  426. 确保使用的是最新版本,旧版本可能存在事件循环阻塞问题。
  427. ---
  428. ## System Requirements
  429. - **Python**: 3.10+
  430. - **ComfyUI**: 最新版本
  431. - **GPU**: 推荐 8GB+ 显存(Anima 模型较大)
  432. - **依赖**:`mcp`(MCP Server)、`requests`(可选,HTTP 请求)
  433. ---
  434. ## Credits
  435. - **Anima Model**: [circlestone-labs/Anima](https://huggingface.co/circlestone-labs/Anima)
  436. - **ComfyUI**: [comfyanonymous/ComfyUI](https://github.com/comfyanonymous/ComfyUI)
  437. - **MCP Protocol**: [Anthropic Model Context Protocol](https://github.com/anthropics/anthropic-cookbook/tree/main/misc/model_context_protocol)
  438. ---
  439. ## License
  440. AGPL-3.0 License - see [LICENSE](LICENSE) for details.
  441. ---
  442. ## Contributing
  443. 欢迎提交 Issue 和 Pull Request!
  444. 1. Fork 本仓库
  445. 2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
  446. 3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
  447. 4. 推送到分支 (`git push origin feature/AmazingFeature`)
  448. 5. 打开一个 Pull Request

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.