shield_lock
金大哥
← 返回 MCP 目录
public公开dns本地运行

comfyui-animatool

ComfyUI-AnimaTool是一个让AI Agent直接生成二次元图片并原生显示在聊天窗口的工具，通过MCP协议或HTTP API连接ComfyUI，支持结构化提示词、多长宽比、批量生成和LoRA加载等功能。

article

README

🚀 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 对应目录： | 文件 | 路径 | 说明 | |------|------|------| | 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

使用

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

  • 方式 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 对应目录： | 文件 | 路径 | 说明 | |------|------|------| | 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

💻 使用示例

方式 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

配置

环境变量（推荐）

所有配置都可以通过环境变量覆盖，无需修改代码：

基础配置

| 环境变量 | 默认值 | 说明 | |----------|--------|------| | COMFYUI_URL | http://127.0.0.1:8188 | ComfyUI 服务地址 | | ANIMATOOL_TIMEOUT | 600 | 生成超时（秒） | | ANIMATOOL_DOWNLOAD_IMAGES | true | 是否保存图片到本地 | | ANIMATOOL_OUTPUT_DIR | ./outputs | 图片输出目录 | | ANIMATOOL_TARGET_MP | 1.0 | 目标像素数（MP） | | ANIMATOOL_ROUND_TO | 16 | 分辨率对齐倍数 |

模型配置

| 环境变量 | 默认值 | 说明 | |----------|--------|------| | COMFYUI_MODELS_DIR | (未设置) | ComfyUI models 目录路径，用于模型预检查；同时也用于 LoRA sidecar 元数据读取（list_anima_models(model_type="loras")） | | ANIMATOOL_UNET_NAME | anima-preview.safetensors | UNET 模型文件名 | | ANIMATOOL_CLIP_NAME | qwen_3_06b_base.safetensors | CLIP 模型文件名 | | ANIMATOOL_VAE_NAME | qwen_image_vae.safetensors | VAE 模型文件名 | | ANIMATOOL_CHECK_MODELS | true | 是否启用模型预检查 |

在 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 生成图片，推荐安装以下配套插件： | 项目 | 说明 | |------|------| | SillyTavern MCP Client | 酒馆 MCP 客户端，连接 AnimaTool 等 MCP Server，支持 stdio + Streamable HTTP | | SillyTavern Tool Use Fix | 工具调用体验修复，合并碎片消息、图片直接显示在对话中 |

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

参数说明

必需参数

| 参数 | 类型 | 说明 | |------|------|------| | quality_meta_year_safe | string | 质量/年份/安全标签（必须包含 safe/sensitive/nsfw/explicit） | | count | string | 人数（1girl, 2girls, 1boy） | | artist | string | 画师，必须带 @（如 @fkey, @jima） | | tags | string | Danbooru 标签 | | neg | string | 负面提示词 |

可选参数

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | aspect_ratio | string | - | 长宽比（自动计算分辨率） | | width / height | int | - | 直接指定分辨率 | | character | string | "" | 角色名 | | series | string | "" | 作品名 | | appearance | string | "" | 外观描述 | | style | string | "" | 画风 | | environment | string | "" | 环境/光影 | | steps | int | 25 | 步数 | | cfg | float | 4.5 | CFG | | seed | int | 随机 | 种子 | | sampler_name | string | er_sde | 采样器 | | repeat | int | 1 | 提交几次独立生成任务（queue 模式，每次独立随机 seed）。总张数 = repeat × batch_size | | batch_size | int | 1 | 单次任务内生成几张（latent batch 模式，更吃显存） | | loras | array | [] | 可选：追加 LoRA（仅 UNET）。name 为 ComfyUI/models/loras/ 下的相对路径（可含子目录），示例：[{"name":"_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors","weight":0.8}] |

支持的长宽比

横屏: 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 参数

可直接参考本仓库示例：examples/requests/generate_with_cosmic_kaguya_lora.json

{
  "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。

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 解决：确认以下文件存在： | 文件 | 位置 | |------|------| | anima-preview.safetensors | ComfyUI/models/diffusion_models/ | | qwen_3_06b_base.safetensors | ComfyUI/models/text_encoders/ | | qwen_image_vae.safetensors | ComfyUI/models/vae/ | 下载地址：circlestone-labs/Anima

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 请求）

致谢

贡献

欢迎提交 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 版本更稳定。
  • 提示词不分行，单行逗号连接。
help

运行方式说明

cloud

托管运行

托管运行通常表示这个 MCP Server 由服务方环境承载，用户一般按页面提供的连接方式或授权流程接入，不需要在本地长期启动一个 MCP 进程

  1. 打开服务方连接页
  2. 完成授权或复制端点
  3. 在 MCP 客户端中连接
terminal

本地运行 / 其它方式

本地运行通常需要用户在自己的电脑或服务器上安装依赖，把 server_config 复制到 MCP 客户端，并按 env_schema 补齐环境变量、密钥或其它配置

  1. 复制 server_config
  2. 安装所需依赖
  3. 补齐环境变量后重启客户端