Comfyui Animatool

🚀 ComfyUI-AnimaTool

ComfyUI-AnimaTool 是一款強大的工具，能讓 AI Agent 直接生成二次元圖片，並原生顯示在聊天窗口。它支持多種調用方式，還具備豐富的功能特性，為用戶帶來便捷的圖片生成體驗。

🚀 快速開始

安裝

根據不同的使用場景和需求，提供了多種安裝方式：

• Cherry Studio 用戶：需下載 Cherry Studio v1.7.17-preview，安裝後按「方式 1：MCP Server」配置，生成的圖片會直接顯示在聊天窗口。
• ComfyUI Manager（推薦）：打開 ComfyUI Manager，搜索 "Anima Tool"，點擊 Install 後重啟 ComfyUI。
• 手動安裝：

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

模型準備

確保以下模型文件已放置到 ComfyUI 對應目錄：

使用

根據不同的使用需求，提供了多種使用方式：

• 方式 0：獨立 MCP（推薦：雲端/遠程 ComfyUI，或不想裝到 custom_nodes）：使用獨立 PyPI 包 comfyui-animatool，可通過不同方式安裝，安裝後使用命令 animatool-mcp。需在項目根目錄創建 .cursor/mcp.json 進行配置，若雲端 ComfyUI 需要鑑權，可額外設置相關參數。
• 方式 1：MCP Server（推薦，原生圖片顯示）：在項目根目錄創建 .cursor/mcp.json 配置 Cursor，安裝 MCP 依賴 pip install mcp，確保 ComfyUI 運行在 http://127.0.0.1:8188，重啟 Cursor 加載 MCP Server 後，即可讓 AI 生成圖片，圖片會原生顯示在聊天窗口。
• 方式 2：ComfyUI 內置 HTTP API：啟動 ComfyUI 後，以下路由自動註冊： | 路由 | 方法 | 說明 | |------|------|------| | /anima/health | GET | 健康檢查 | | /anima/schema | GET | Tool Schema | | /anima/knowledge | GET | 專家知識 | | /anima/generate | POST | 執行生成（支持 repeat 批量） | | /anima/history | GET | 查看最近生成歷史 | | /anima/reroll | POST | 基於歷史記錄重新生成 | 可參考提供的 PowerShell 和 curl 調用示例進行調用。
• 方式 3：獨立 FastAPI Server：

cd ComfyUI-AnimaTool
pip install fastapi uvicorn
python -m servers.http_server

訪問 http://127.0.0.1:8000/docs 查看 Swagger UI。

✨ 主要特性

• MCP Server：圖片原生顯示在 Cursor/Claude 聊天窗口。
• HTTP API：隨 ComfyUI 啟動，無需額外服務。
• 結構化提示詞：按 Anima 規範自動拼接。
• 多長寬比支持：21:9 到 9:21（共 14 種預設）。
• Reroll / 歷史記錄：支持基於歷史記錄重新生成，可覆蓋部分參數（換畫師、加 LoRA 等）。
• 批量生成：repeat 參數提交多次獨立任務（queue 模式），batch_size 在單任務內生成多張。

📦 安裝指南

Cherry Studio 用戶

1. 下載 Cherry Studio v1.7.17-preview（安裝版或便攜版均可）。
2. 安裝後按下方「方式 1：MCP Server」配置。
3. 生成的圖片會直接顯示在聊天窗口中。

官方版 Cherry Studio 尚未合併此修復，使用官方版會導致圖片顯示為 base64 亂碼，且多輪出圖後會嚴重卡頓。v1.7.17-preview 基於上游 v1.7.17，修復了出圖後內存膨脹和 UI 凍結的問題（詳情）。

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 對應目錄：

💻 使用示例

方式 0：獨立 MCP

安裝

方式一：使用 uvx (推薦，無需安裝) 無需手動安裝 Python 包，直接在 Cursor 配置中使用 uvx 運行（需安裝 uv）。 (配置見下方 JSON)

方式二：使用 pip

pip install comfyui-animatool

方式三：源碼安裝 (開發用)

pip install -e ./animatool-mcp

配置 Cursor

在項目根目錄創建 .cursor/mcp.json（以 uvx 為例）：

{
  "mcpServers": {
    "anima-tool": {
      "command": "uvx",
      "args": ["--from", "comfyui-animatool", "animatool-mcp"],
      "env": {
        "COMFYUI_URL": "http://127.0.0.1:8188",
        "ANIMATOOL_CHECK_MODELS": "false"
      }
    }
  }
}

雲端鑑權（可選）

如果雲端 ComfyUI 需要鑑權（反代/VPN/網關等），可額外設置：

• ANIMATOOL_BEARER_TOKEN
• 或 ANIMATOOL_HEADERS_JSON（自定義 Header JSON 字符串）

方式 1：MCP Server

配置 Cursor

在項目根目錄創建 .cursor/mcp.json：

{
  "mcpServers": {
    "anima-tool": {
      "command": "<PATH_TO_PYTHON>",
      "args": ["<PATH_TO>/ComfyUI-AnimaTool/servers/mcp_server.py"]
    }
  }
}

示例（Windows）：

{
  "mcpServers": {
    "anima-tool": {
      "command": "C:\\ComfyUI\\.venv\\Scripts\\python.exe",
      "args": ["C:\\ComfyUI\\custom_nodes\\ComfyUI-AnimaTool\\servers\\mcp_server.py"]
    }
  }
}

安裝 MCP 依賴

pip install mcp

使用

1. 確保 ComfyUI 運行在 http://127.0.0.1:8188。
2. 重啟 Cursor 加載 MCP Server。
3. 直接讓 AI 生成圖片：

畫一個穿白裙的少女在花園裡，豎屏 9:16，safe

方式 2：ComfyUI 內置 HTTP API

調用示例

PowerShell：

$body = @{
    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"
} | ConvertTo-Json -Depth 10

Invoke-RestMethod -Uri "http://127.0.0.1:8188/anima/generate" -Method Post -Body $body -ContentType "application/json"

curl：

curl -X POST http://127.0.0.1:8188/anima/generate \
  -H "Content-Type: application/json" \
  -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"}'

方式 3：獨立 FastAPI Server

cd ComfyUI-AnimaTool
pip install fastapi uvicorn
python -m servers.http_server

訪問 http://127.0.0.1:8000/docs 查看 Swagger UI。

📚 詳細文檔

• 📖 Wiki & Prompt Guide - 詳細的提示詞指南、安裝教程和 API 文檔。
• 🤖 Cursor Skill - Cursor / Windsurf 用戶必讀！將此文件內容作為 Agent Skill，讓 AI 學會如何寫高質量提示詞。

🔧 技術細節

目錄結構

ComfyUI-AnimaTool/
├── __init__.py           # ComfyUI extension（註冊 /anima/* 路由）
├── executor/             # 核心執行器
│   ├── anima_executor.py
│   ├── config.py
│   ├── history.py        # 生成歷史管理器（內存 + JSONL 持久化）
│   └── workflow_template.json
├── knowledge/            # 專家知識庫
│   ├── anima_expert.md
│   ├── artist_list.md
│   └── prompt_examples.md
├── schemas/              # Tool Schema
│   └── tool_schema_universal.json
├── servers/
│   ├── mcp_server.py     # MCP Server（原生圖片返回）
│   ├── http_server.py    # 獨立 FastAPI
│   └── cli.py            # 命令行工具
├── assets/               # 截圖等資源
├── outputs/              # 生成的圖片（gitignore）
├── README.md
├── LICENSE
├── CHANGELOG.md
├── pyproject.toml
└── requirements.txt

配置

環境變量（推薦）

所有配置都可以通過環境變量覆蓋，無需修改代碼：

基礎配置

模型配置

在 Cursor MCP 配置中設置環境變量

{
  "mcpServers": {
    "anima-tool": {
      "command": "C:\\ComfyUI\\.venv\\Scripts\\python.exe",
      "args": ["C:\\ComfyUI\\custom_nodes\\ComfyUI-AnimaTool\\servers\\mcp_server.py"],
      "env": {
        "COMFYUI_URL": "http://127.0.0.1:8188",
        "COMFYUI_MODELS_DIR": "C:\\ComfyUI\\models"
      }
    }
  }
}

模型預檢查

設置 COMFYUI_MODELS_DIR 後，生成前會自動檢查模型文件是否存在。如果缺少模型文件，會給出友好提示。遠程 ComfyUI 場景若不設置 COMFYUI_MODELS_DIR，則跳過預檢查。

遠程/Docker ComfyUI 配置

如果 ComfyUI 不在本機運行，可根據不同情況設置 COMFYUI_URL：

• 局域網其他電腦：

export COMFYUI_URL=http://192.168.1.100:8188

• Docker 容器訪問宿主機：

export COMFYUI_URL=http://host.docker.internal:8188

• WSL 訪問 Windows：

export COMFYUI_URL=http://$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):8188

📄 許可證

AGPL-3.0 License - 詳情見 LICENSE。

相關項目

SillyTavern 全家桶

在 SillyTavern（酒館）中使用 AnimaTool 生成圖片，推薦安裝以下配套插件：

ComfyUI-AnimaTool (本項目，MCP Server)
        ↕ MCP 協議 (stdio / streamable-http)
SillyTavern MCP Client (連接 + 工具註冊)
        ↕ SillyTavern Tool Calling
Tool Use Fix (合併顯示 + 體驗優化)

AnimaLoraToolkit - LoRA 訓練工具

如果你想訓練自己的 LoRA/LoKr 來搭配 Anima 使用，推薦使用 AnimaLoraToolkit：

• YAML 配置文件 - 通過 --config 加載，命令行參數可覆蓋。
• LoRA / LoKr 雙模式 - 標準 LoRA 和 LyCORIS LoKr。
• ComfyUI 兼容 - 輸出的 safetensors 可直接在本工具中使用。
• JSON Caption 支持 - 結構化標籤，分類 shuffle。
• 即時訓練監控 - Web 界面顯示 loss 曲線和採樣圖。
• Checkpoint 恢復 - 保存完整訓練狀態，支持斷點續訓。

訓練完成後，將 LoRA 放入 ComfyUI/models/loras/ 目錄，即可通過本工具的 loras 參數加載使用。

示例：Cosmic Princess Kaguya LoKr

使用 AnimaLoraToolkit 訓練的畫風+角色 LoKr，還原 Netflix 動畫電影《超時空輝耀姬！》的 4K 劇場版畫風：

• 下載：Civitai
• 觸發詞：@spacetime kaguya（畫風）、cosmic princess kaguya（作品）
• 推薦權重：0.8 - 1.0

參數說明

必需參數

可選參數

支持的長寬比

橫屏: 21:9, 2:1, 16:9, 16:10, 5:3, 3:2, 4:3
方形: 1:1
豎屏: 3:4, 2:3, 3:5, 10:16, 9:16, 1:2, 9:21

LoRA（可選）

當前版本會在 UNETLoader → KSampler(model) 之間鏈式注入 LoraLoaderModelOnly，因此只對 UNET 生效（不會改 CLIP）。

1）把 LoRA 放到 ComfyUI 的 loras 目錄

你的 LoRA 路徑（示例）：

• G:\\AIGC\\ComfyUICommon\\models\\loras\\_Anima\\cosmic_kaguya_lokr_epoch4_comfyui.safetensors 對應請求裡 loras[i].name 應寫為（相對 models/loras/）：
• 推薦寫法：_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors

說明：ComfyUI 側實際會校驗 lora_name 是否在 GET /models/loras 的返回列表裡。

• Windows 環境下該列表通常是反斜槓路徑（例如 _Anima\\cosmic_kaguya_lokr_epoch4_comfyui.safetensors）
• 本項目會根據 /models/loras 返回值自動規範化分隔符（你用 / 或 \\ 都可以），但如果你直接在 ComfyUI 裡手工填 lora_name，請務必複製接口返回值。

2）生成時傳入 loras 參數

可直接參考本倉庫示例：

{
  "aspect_ratio": "3:4",
  "quality_meta_year_safe": "newest, year 2024, safe",
  "count": "1girl",
  "character": "kaguya",
  "series": "cosmic princess kaguya",
  "artist": "@spacetime kaguya",
  "appearance": "long hair, black hair, purple eyes",
  "tags": "school uniform, smile, standing, looking at viewer",
  "environment": "classroom, window, sunlight",
  "nltags": "A cheerful girl stands by the window.",
  "neg": "worst quality, low quality, blurry, bad hands, nsfw",
  "loras": [
    {
      "name": "_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors",
      "weight": 0.9
    }
  ]
}

3）（可選）為 LoRA 寫 sidecar 元數據，讓 MCP 的 list 工具可見

為了避免把整個 loras 目錄無差別暴露給 MCP 客戶端，本項目在 list_anima_models(model_type="loras") 時強制只返回存在同名 .json sidecar 元數據文件的 LoRA。

• LoRA 文件：ComfyUI/models/loras/_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors
• sidecar：ComfyUI/models/loras/_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors.json 示例 sidecar 文件可參考：

sidecar JSON 的字段結構完全自定義，本項目只要求其為合法 JSON。 注意：要讓 MCP 服務端讀取該 sidecar，你還需要設置 COMFYUI_MODELS_DIR 指向本機的 models 根目錄（例如 C:\\ComfyUI\\models；你的示例則是 G:\\AIGC\\ComfyUICommon\\models）。遠程 ComfyUI 場景通常無法讀取遠程文件系統，因此只支持“直接使用 loras 參數”，不支持 list。

重要規則

1. 畫師必須帶 @：如 @fkey, @jima，否則幾乎無效。
2. 必須明確安全標籤：safe / sensitive / nsfw / explicit。
3. 推薦畫師組合：@fkey, @jima（效果穩定）。
4. 分辨率約 1MP：Anima preview 版本更穩定。
5. 提示詞不分行：單行逗號連接。

故障排除

錯誤：無法連接到 ComfyUI

症狀：Connection refused 或 無法連接到 ComfyUI 排查步驟：

1. 確認 ComfyUI 已啟動：瀏覽器訪問 http://127.0.0.1:8188。
2. 確認端口正確：默認 8188，如果改過需要設置 COMFYUI_URL。
3. 確認防火牆未阻止（Windows Defender / 企業防火牆）。
4. 如果 ComfyUI 在遠程/Docker，設置正確的 COMFYUI_URL。

錯誤：H,W should be divisible by spatial_patch_size

症狀：H,W (xxx, xxx) should be divisible by spatial_patch_size 2 原因：分辨率不是 16 的倍數 解決：

• 使用預設的 aspect_ratio（如 16:9、9:16、1:1）。
• 如果手動指定 width/height，確保是 16 的倍數（如 512、768、1024）。

錯誤：模型文件不存在

症狀：ComfyUI 控制檯報 FileNotFoundError 或 Model not found 解決：確認以下文件存在：

MCP Server 沒加載？

1. 檢查狀態：Cursor Settings → MCP → anima-tool 應顯示綠色。
2. 查看日誌：點擊 "Show Output" 查看錯誤。
3. 確認路徑：Python 和腳本路徑必須是絕對路徑。
4. 確認依賴：pip install mcp（使用 ComfyUI 的 Python 環境）。
5. 重啟 Cursor：修改配置後必須重啟。

生成超時？

症狀：等待很久後報 TimeoutError 可能原因：

• ComfyUI 正在加載模型（首次生成較慢）。
• GPU 顯存不足導致處理緩慢。
• 步數 steps 設置過高。 解決：
• 增加超時時間：export ANIMATOOL_TIMEOUT=1200。
• 降低步數：steps: 25（默認值）。
• 檢查 ComfyUI 控制檯是否有錯誤。

API 調用卡住？

確保使用的是最新版本，舊版本可能存在事件循環阻塞問題。

系統要求

• Python: 3.10+
• ComfyUI: 最新版本
• GPU: 推薦 8GB+ 顯存（Anima 模型較大）
• 依賴：mcp（MCP Server）、requests（可選，HTTP 請求）

致謝

• Anima Model: circlestone-labs/Anima
• ComfyUI: comfyanonymous/ComfyUI
• MCP Protocol: Anthropic Model Context Protocol

貢獻

歡迎提交 Issue 和 Pull Request！

1. Fork 本倉庫。
2. 創建你的特性分支 (git checkout -b feature/AmazingFeature)。
3. 提交你的更改 (git commit -m 'Add some AmazingFeature')。
4. 推送到分支 (git push origin feature/AmazingFeature)。
5. 打開一個 Pull Request。

⚠️ 重要提示

• 今日更新了十連抽、更換卡池和尋訪記錄功能，同時雲端/遠程連接更簡單，酒館 MCP 客戶端已發佈，工具調用體驗也得到修復。
• Cherry Studio 現已支持 MCP 圖片顯示，可下載預覽版體驗完整功能。

💡 使用建議

• 畫師必須帶 @，如 @fkey, @jima，否則幾乎無效。
• 必須明確安全標籤，如 safe / sensitive / nsfw / explicit。
• 推薦畫師組合為 @fkey, @jima，效果穩定。
• 分辨率約 1MP 時，Anima preview 版本更穩定。
• 提示詞不分行，單行逗號連接。