Comfyui Animatool

🚀 ComfyUI-AnimaTool

ComfyUI-AnimaTool enables AI agents to directly generate anime - style images and display them natively in the chat window, providing a seamless and efficient image - generation experience.

⚠️ Important Note

Today's Updates

• 🎰 Ten - draw feature — Supports repeat / batch_size, allowing you to generate multiple images at once.
• 🔄 Card pool replacement feature — You can switch between UNET / CLIP / VAE models. Try the new card pool!
• 📋 Summon history feature — View historical generation records and support rerolling.

✅ Easier cloud/remote connection — A new uvx installation - free mode is added. You can connect to a remote ComfyUI with one - line configuration, no local environment required. ✅ Tavern MCP Client released — SillyTavern MCP Client, supporting stdio + Streamable HTTP transmission.

✅ Tool call experience fixed — Tool Use Fix, which merges fragmented messages, displays images directly, and uses Swipe proxy.

💡 Usage Tip

Cherry Studio now supports MCP image display!
Our submitted PR has fixed Cherry Studio's handling of MCP ImageContent. Before the official merge, you can use the preview version to experience the full MCP image functionality:
Download the preview version → Cherry Studio v1.7.17 - preview
It includes the following fixes:

• Support for configuring whether to send MCP tool images to the model for each assistant separately.
• Fix for base64 image data processing of OpenAI - compatible providers.
• Fix for MCP multimodal tool result conversion of Gemini.
• Performance fix v2: Resolve the severe lag issue after multiple rounds of image generation — IPC excludes large slices + base64 in - place strip (fixes the issue where Zod safeParse cloning made strip ineffective in v1.7.16 - preview2) — Upstream PR #12766

Let AI agents directly generate anime images and display them natively in the chat window

Cursor / Claude / Gemini / OpenAI → MCP / HTTP API → ComfyUI → Anima model

🚀 Quick Start

Get started with ComfyUI - AnimaTool to leverage its powerful image - generation capabilities.

✨ Features

• MCP Server: Display images natively in the Cursor/Claude chat window.
• HTTP API: Starts with ComfyUI, no additional services required.
• Structured prompts: Automatically splice according to the Anima specification.
• Multiple aspect ratio support: From 21:9 to 9:21 (14 presets in total).
• Reroll / History: Support regenerating based on historical records, and override some parameters (change the artist, add LoRA, etc.).
• Batch generation: Use the repeat parameter to submit multiple independent tasks (queue mode), and batch_size to generate multiple images within a single task.

📦 Installation

For Cherry Studio users

If you use Cherry Studio as an MCP client, you need to install our preview version to correctly display the images returned by MCP:

1. Download Cherry Studio v1.7.17 - preview (either the installation version or the portable version).
2. After installation, configure it as described in "Method 1: MCP Server" below.
3. The generated images will be directly displayed in the chat window.

The official version of Cherry Studio has not merged this fix. Using the official version will cause the images to be displayed as base64 garbled code, and there will be severe lag after multiple rounds of image generation.
v1.7.17 - preview is based on the upstream v1.7.17, which fixes the issues of memory inflation and UI freezing after image generation (Details).

Method 1: ComfyUI Manager (Recommended)

1. Open ComfyUI Manager.
2. Search for "Anima Tool".
3. Click Install.
4. Restart 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

Ensure that the following model files are placed in the corresponding ComfyUI directories:

Download the models: circlestone - labs/Anima on Hugging Face

💻 Usage Examples

Method 0: Stand - alone MCP (Recommended for cloud/remote ComfyUI or those who don't want to install it in custom_nodes)

If you only want to connect to a running ComfyUI (local or cloud) and don't want to put this repository into ComfyUI/custom_nodes/, you can use the stand - alone PyPI package comfyui-animatool (use the command animatool-mcp after installation) (it only works through the ComfyUI standard APIs: /prompt, /history/<id>, /view?...).

Installation

Method 1: Use uvx (Recommended, no installation required) No need to manually install Python packages. Use uvx to run directly in the Cursor configuration (you need to install uv): (See the JSON configuration below)

Method 2: Use pip

pip install comfyui-animatool

Method 3: Install from source code (for development)

pip install -e ./animatool-mcp

Configure Cursor

Create .cursor/mcp.json in the project root directory (using uvx as an example):

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

Cloud authentication (Optional)

If the cloud ComfyUI requires authentication (reverse proxy/VPN/gateway, etc.), you can additionally set:

• ANIMATOOL_BEARER_TOKEN
• or ANIMATOOL_HEADERS_JSON (custom Header JSON string)

This method does not depend on installing this custom node; as long as COMFYUI_URL is accessible.

Method 1: MCP Server (Recommended, native image display)

Configure Cursor

Create .cursor/mcp.json in the project root directory:

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

Example (Windows):

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

Install MCP dependencies

pip install mcp

Usage

1. Ensure that ComfyUI is running at http://127.0.0.1:8188.
2. Restart Cursor to load the MCP Server.
3. Directly ask the AI to generate an image:

Draw a girl in a white dress in a garden, vertical screen 9:16, safe

The image will be natively displayed in the chat window.

Method 2: ComfyUI built - in HTTP API

After starting ComfyUI, the following routes are automatically registered:

Call examples

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"}'

Method 3: Stand - alone FastAPI Server

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

Visit http://127.0.0.1:8000/docs to view the Swagger UI.

📚 Documentation

• 📖 Wiki & Prompt Guide - Detailed prompt guides, installation tutorials, and API documentation.
• 🤖 Cursor Skill - A must - read for Cursor / Windsurf users! Use the content of this file as an Agent Skill to let the AI learn how to write high - quality prompts.

🔧 Technical Details

Parameters

Required

Optional

Supported Aspect Ratios

Landscape: 21:9, 2:1, 16:9, 16:10, 5:3, 3:2, 4:3
Square: 1:1
Portrait: 3:4, 2:3, 3:5, 10:16, 9:16, 1:2, 9:21

LoRA (Optional)

In the current version, LoraLoaderModelOnly is chained between UNETLoader → KSampler(model), so it only works for UNET (CLIP is not modified).

1) Place the LoRA in the ComfyUI loras directory

Your LoRA path (example):

• G:\\AIGC\\ComfyUICommon\\models\\loras\\_Anima\\cosmic_kaguya_lokr_epoch4_comfyui.safetensors

The corresponding loras[i].name in the request should be written as (relative to models/loras/):

• Recommended writing: _Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors

Note: ComfyUI will actually check if lora_name is in the list returned by GET /models/loras.

• In a Windows environment, this list usually uses backslash paths (e.g., _Anima\\cosmic_kaguya_lokr_epoch4_comfyui.safetensors).
• This project will automatically standardize the separators based on the value returned by /models/loras (you can use / or \\), but if you manually fill in lora_name in ComfyUI, please copy the value returned by the interface.

2) Pass the loras parameter during generation

You can directly refer to the example in this repository:

{
  "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) (Optional) Write sidecar metadata for the LoRA to make it visible in the MCP list tool

To avoid exposing the entire loras directory to the MCP client without discrimination, this project only returns LoRAs with a sidecar metadata file of the same name in JSON format when list_anima_models(model_type="loras").

• LoRA file: ComfyUI/models/loras/_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors
• Sidecar: ComfyUI/models/loras/_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors.json

You can refer to the example sidecar file:

The field structure of the sidecar JSON is completely customizable. This project only requires it to be valid JSON.

Note: To make the MCP server read this sidecar, you also need to set COMFYUI_MODELS_DIR to point to the local models root directory (e.g., C:\\ComfyUI\\models; in your example, it is G:\\AIGC\\ComfyUICommon\\models). In the case of a remote ComfyUI, the remote file system usually cannot be accessed, so only "directly using the loras parameter" is supported, and the list function is not supported.

Directory Structure

ComfyUI-AnimaTool/
├── __init__.py           # ComfyUI extension (registers /anima/* routes)
├── executor/             # Core executor
│   ├── anima_executor.py
│   ├── config.py
│   ├── history.py        # Generation history manager (in - memory + JSONL persistence)
│   └── workflow_template.json
├── knowledge/            # Expert knowledge base
│   ├── anima_expert.md
│   ├── artist_list.md
│   └── prompt_examples.md
├── schemas/              # Tool Schema
│   └── tool_schema_universal.json
├── servers/
│   ├── mcp_server.py     # MCP Server (returns images natively)
│   ├── http_server.py    # Stand - alone FastAPI
│   └── cli.py            # Command - line tool
├── assets/               # Resources such as screenshots
├── outputs/              # Generated images (gitignore)
├── README.md
├── LICENSE
├── CHANGELOG.md
├── pyproject.toml
└── requirements.txt

Configuration

Environment variables (Recommended)

All configurations can be overridden through environment variables without modifying the code:

Basic configuration

Model configuration

Set environment variables in the Cursor MCP configuration

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

Model pre - checking

After setting COMFYUI_MODELS_DIR, the model files will be automatically checked for existence before generation:

"env": {
  "COMFYUI_MODELS_DIR": "C:\\ComfyUI\\models"
}

If a model file is missing, a friendly prompt will be given:

The following model files are missing:
  - unet: diffusion_models/anima-preview.safetensors
  - clip: text_encoders/qwen_3_06b_base.safetensors

Please download from HuggingFace: https://huggingface.co/circlestone-labs/Anima
and place them in the corresponding sub - directories of ComfyUI/models/

Remote ComfyUI scenario: If COMFYUI_MODELS_DIR is not set, the pre - checking will be skipped (because the remote file system cannot be accessed).

Remote/Docker ComfyUI configuration

If ComfyUI is not running on the local machine: Another computer on the local network:

export COMFYUI_URL=http://192.168.1.100:8188

Docker container accessing the host:

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

WSL accessing Windows:

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

📄 License

This project is licensed under the AGPL - 3.0 License. See LICENSE for details.

Related Projects

SillyTavern Suite

Want to use AnimaTool to generate images in SillyTavern? We recommend installing the following supporting plugins:

ComfyUI-AnimaTool (This project, MCP Server)
        ↕ MCP protocol (stdio / streamable-http)
SillyTavern MCP Client (Connection + Tool registration)
        ↕ SillyTavern Tool Calling
Tool Use Fix (Merged display + Experience optimization)

AnimaLoraToolkit - LoRA Training Tool

If you want to train your own LoRA/LoKr to use with Anima, we recommend using AnimaLoraToolkit:

• YAML configuration file - Loaded via --config, command - line parameters can override it.
• LoRA / LoKr dual mode - Standard LoRA and LyCORIS LoKr.
• ComfyUI compatible - The output safetensors can be directly used in this tool.
• JSON Caption support - Structured tags, classified shuffle.
• Real - time training monitoring - Displays the loss curve and sampled images on the Web interface.
• Checkpoint recovery - Saves the complete training state and supports resuming training from a breakpoint.

After training, place the LoRA in the ComfyUI/models/loras/ directory, and you can load and use it through the loras parameter of this tool.

Example: Cosmic Princess Kaguya LoKr

A style + character LoKr trained using AnimaLoraToolkit, restoring the 4K theatrical - version style of the Netflix animated movie Space - Time Kaguya!:

• Download: Civitai
• Trigger words: @spacetime kaguya (style), cosmic princess kaguya (work)
• Recommended weight: 0.8 - 1.0

Troubleshooting

Error: Unable to connect to ComfyUI

Symptom: Connection refused or Unable to connect to ComfyUI Troubleshooting steps:

1. Confirm that ComfyUI is running: Visit http://127.0.0.1:8188 in your browser.
2. Confirm that the port is correct: The default is 8188. If you have changed it, you need to set COMFYUI_URL.
3. Confirm that the firewall is not blocking (Windows Defender / corporate firewall).
4. If ComfyUI is running remotely/in a Docker container, set the correct COMFYUI_URL.

Error: H,W should be divisible by spatial_patch_size

Symptom: H,W (xxx, xxx) should be divisible by spatial_patch_size 2 Cause: The resolution is not a multiple of 16. Solution:

• Use the preset aspect_ratio (e.g., 16:9, 9:16, 1:1).
• If you manually specify width/height, ensure that it is a multiple of 16 (e.g., 512, 768, 1024).

Error: Model file not found

Symptom: The ComfyUI console reports FileNotFoundError or Model not found Solution: Confirm that the following files exist:

Download address: circlestone - labs/Anima

MCP Server not loaded?

1. Check the status: In Cursor Settings → MCP → anima - tool should show green.
2. View the logs: Click "Show Output" to view the error.
3. Confirm the path: The Python and script paths must be absolute paths.
4. Confirm the dependencies: pip install mcp (using the ComfyUI Python environment).
5. Restart Cursor: You must restart after modifying the configuration.

Generation timeout?

Symptom: After waiting for a long time, TimeoutError is reported. Possible causes:

• ComfyUI is loading the model (the first generation is slower).
• Insufficient GPU memory causes slow processing.
• The steps parameter is set too high. Solutions:
• Increase the timeout: export ANIMATOOL_TIMEOUT=1200
• Reduce the number of steps: steps: 25 (default value)
• Check the ComfyUI console for errors.

API call stuck?

Ensure that you are using the latest version. Older versions may have event - loop blocking issues.

System Requirements

• Python: 3.10+
• ComfyUI: The latest version
• GPU: Recommended 8GB+ VRAM (the Anima model is large)
• Dependencies: mcp (MCP Server), requests (optional, for HTTP requests)

Credits

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

Contributing

We welcome you to submit issues and pull requests!

1. Fork this repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a pull request.