Comfyui Animatool

🚀 ComfyUI-AnimaTool

AIエージェントによる二次元画像の直接生成とチャットウィンドウでの表示を可能にするツール

🚀 クイックスタート

ComfyUI-AnimaToolは、AIエージェントが二次元画像を直接生成し、チャットウィンドウに表示することを可能にするツールです。以下のセクションで、機能、インストール方法、使用方法などを詳しく説明します。

⚠️ 重要提示

今日の更新内容は以下の通りです。

• 🎰 十連抽機能 — repeat / batch_size をサポートし、一度に複数枚の画像を生成できます。
• 🔄 カードプール切り替え機能 — UNET / CLIP / VAE モデルを切り替えることができます。新しいカードプールを試してみましょう。
• 📋 抽選履歴機能 — 過去の生成履歴を確認でき、reroll で再抽選が可能です。

✅ クラウド/リモート接続が簡単に — 新しく uvx 免インストールモードが追加され、一行の設定でリモートのComfyUIに接続できます。ローカル環境は不要です。 ✅ SillyTavern MCP クライアントが公開されました — SillyTavern MCP Client は、stdio + Streamable HTTP 転送をサポートしています。

✅ ツール呼び出しの体験が改善されました — Tool Use Fix で、断片的なメッセージを統合し、画像を直接表示し、Swipe プロキシを使用できます。

💡 使用建议

Cherry Studio では、MCP 画像表示がサポートされるようになりました！
提出した PR で、Cherry Studio の MCP ImageContent の処理が修正されました。公式でマージされる前に、プレビュー版を使用して完全な MCP 画像機能を体験できます。
プレビュー版をダウンロード → Cherry Studio v1.7.17-preview
以下の修正が含まれています。

• アシスタントごとに、MCP ツール画像をモデルに送信するかどうかを個別に設定できるようになりました。
• OpenAI 互換プロバイダの base64 画像データの処理が修正されました。
• Gemini の MCP マルチモーダルツール結果の変換が修正されました。
• パフォーマンス修正 v2：複数回の画像生成後の深刻な遅延問題を解決しました — IPC から大きなスライスを除外し、base64 をその場で strip します（v1.7.16-preview2 での Zod safeParse クローンによる strip 無効の問題を修正しました）— 上流 PR #12766

✨ 主な機能

• MCP Server：画像を Cursor/Claude のチャットウィンドウに直接表示します。
• HTTP API：ComfyUI とともに起動し、追加のサービスは不要です。
• 構造化プロンプト：Anima の規範に従って自動的にプロンプトを結合します。
• 複数のアスペクト比サポート：21:9 から 9:21 まで（合計 14 種類のプリセット）。
• Reroll / 履歴記録：過去の記録に基づいて再生成をサポートし、一部のパラメータを上書きできます（画家の変更、LoRA の追加など）。
• バッチ生成：repeat パラメータで複数の独立したタスクを送信し（queue モード）、batch_size で単一のタスク内で複数枚の画像を生成します。

📦 インストール

Cherry Studio ユーザー

Cherry Studio を MCP クライアントとして使用する場合、MCP から返される画像を正しく表示するには、プレビュー版をインストールする必要があります。

1. Cherry Studio v1.7.17-preview をダウンロードします（インストール版またはポータブル版）。
2. インストール後、以下の「方法 1：MCP Server」の設定を行います。
3. 生成された画像はチャットウィンドウに直接表示されます。

公式版の Cherry Studio ではこの修正がまだマージされていないため、公式版を使用すると画像が base64 の乱符号として表示され、複数回の画像生成後に深刻な遅延が発生します。
v1.7.17-preview は上流の v1.7.17 をベースに、画像生成後のメモリ膨張と UI 凍結の問題を修正しています（詳細）。

方法 1: ComfyUI Manager (推奨)

1. ComfyUI Manager を開きます。
2. "Anima Tool" を検索します。
3. Install をクリックします。
4. ComfyUI を再起動します。

方法 2: 手動インストール

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

前提条件

以下のモデルファイルが ComfyUI の対応するディレクトリに配置されていることを確認してください。

モデルのダウンロード：circlestone-labs/Anima on Hugging Face

💻 使用例

方式 0：独立 MCP（推奨：クラウド/リモート ComfyUI、または custom_nodes にインストールしたくない場合）

実行中の ComfyUI（ローカルまたはクラウド）に接続し、このリポジトリを ComfyUI/custom_nodes/ に入れたくない場合は、独立した PyPI パッケージ comfyui-animatool を使用できます（インストール後は animatool-mcp コマンドを使用）。この方法は ComfyUI の標準 API（/prompt、/history/<id>、/view?...）のみを使用します。

インストール

方法一：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（カスタムヘッダの JSON 文字列）

この方法はこの custom node のインストールに依存せず、COMFYUI_URL にアクセスできれば動作します。

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

ComfyUI を起動すると、以下のルートが自動的に登録されます。

呼び出し例

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 が高品質なプロンプトを作成する方法を学習できます。

🔧 技術詳細

必須パラメータ

オプションパラメータ

サポートされるアスペクト比

横長: 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 のサイドカーメタデータを作成し、MCP のリストツールで表示可能にする

MCP クライアントに loras ディレクトリ全体を無差別に公開するのを避けるため、このプロジェクトでは list_anima_models(model_type="loras") を実行すると、同名の .json サイドカーメタデータファイルが存在する LoRA のみを返します。

• LoRA ファイル：ComfyUI/models/loras/_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors
• サイドカーメタデータ：ComfyUI/models/loras/_Anima/cosmic_kaguya_lokr_epoch4_comfyui.safetensors.json

サイドカーメタデータファイルの例は以下を参照してください。

サイドカーメタデータの JSON フィールド構造は完全にカスタマイズ可能で、このプロジェクトでは合法な JSON であることのみ要求します。

注意：MCP サーバーがサイドカーメタデータを読み取るには、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 のプレビューバージョンではより安定します。
5. プロンプトは一行で、カンマで区切る

ディレクトリ構造

ComfyUI-AnimaTool/
├── __init__.py           # ComfyUI 拡張（/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_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 を設定すると、生成前にモデルファイルの存在を自動的にチェックします。

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

モデルファイルが不足している場合、以下のような友好的なメッセージが表示されます。

以下のモデルファイルが不足しています：
  - unet: diffusion_models/anima-preview.safetensors
  - clip: text_encoders/qwen_3_06b_base.safetensors

HuggingFace からダウンロードしてください：https://huggingface.co/circlestone-labs/Anima
ComfyUI/models/ の対応するサブディレクトリに配置してください。

リモート ComfyUI の場合：COMFYUI_MODELS_DIR を設定しない場合は、事前チェックをスキップします（リモートファイルシステムにアクセスできないため）。

リモート/Docker ComfyUI の設定

ComfyUI がローカルで実行されていない場合：

ローカルネットワーク内の他のコンピュータ：

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

トラブルシューティング

エラー：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 が表示されます。

解決策：以下のファイルが存在することを確認してください。

ダウンロード先：circlestone-labs/Anima

MCP Server が読み込まれない場合

1. 状態を確認する：Cursor Settings → MCP → anima-tool が緑色で表示されていることを確認します。
2. ログを確認する："Show Output" をクリックしてエラーを確認します。
3. パスを確認する：Python とスクリプトのパスは絶対パスである必要があります。
4. 依存関係を確認する：pip install mcp を実行してください（ComfyUI の Python 環境を使用）。
5. Cursor を再起動する：設定を変更した後は、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

📄 ライセンス

AGPL-3.0 ライセンス - 詳細は LICENSE を参照してください。

コントリビューション

Issue と Pull Request の投稿を歓迎します！

1. このリポジトリをフォークします。
2. 新しい機能ブランチを作成します (git checkout -b feature/AmazingFeature)。
3. 変更をコミットします (git commit -m 'Add some AmazingFeature')。
4. ブランチにプッシュします (git push origin feature/AmazingFeature)。
5. Pull Request を作成します。