anime-diffusion-mcp

MCP server for anime image generation with Animagine XL 4.0.Gives AI agents four tools: validate and optimize Danbooru-style prompts, list local models, and generate images (text-to-image or image-to-image) with custom checkpoints and LoRAs.

Requirements

Python 3.11+
NVIDIA GPU with ~7 GB VRAM recommended (CPU works, but is very slow)
~7 GB of disk for the base model (downloaded from HuggingFace on first generation)

Installation

git clone https://github.com/gabrielalmir/anime-diffusion-mcp.git
cd anime-diffusion-mcp
python -m venv .venv
# Windows: .venv\Scripts\activate  |  Linux/macOS: source .venv/bin/activate
pip install -e .

For CUDA, install the matching PyTorch build first (see https://pytorch.org/get-started/locally/), then pip install -e ..

MCP client configuration

Add the server to your MCP client (Claude Desktop, Claude Code, Cursor, ...). See .mcp.json.example:

{
  "mcpServers": {
    "anime-diffusion": {
      "command": "anime-diffusion-mcp",
      "env": { "CUDA_VISIBLE_DEVICES": "0" }
    }
  }
}

If the client doesn't inherit your virtualenv, point command at the venv script, e.g. C:/path/to/.venv/Scripts/anime-diffusion-mcp.exe.

The server runs over stdio and uses the current working directory for checkpoints/, loras/ and outputs/, so launch it from the project folder (or set cwd in the client config).

Tools

Tool	Purpose
`validate_prompt(prompt, width, height, negative_prompt)`	Check a prompt against Animagine XL rules: quality tags present and last, 8+ tags, character/series consistency, resolution risk. Returns `valid`, `issues`, `suggestions`.
`optimize_prompt(description \| prompt)`	Reorder tags into canonical order (subject → character → series → appearance → composition → environment → style → quality) and fill missing essentials. Returns `optimized_prompt`, `actions`, `warnings`.
`list_models()`	Discover checkpoints in `checkpoints/` and LoRAs in `loras/`.
`generate_image(prompt, ...)`	Generate an image. Pass `image_path` for img2img. Supports `checkpoint`, `loras` + `lora_scales`, `width`/`height`, `steps`, `guidance_scale`, `seed`, `render_type`.

Typical agent flow: optimize_prompt → validate_prompt → generate_image.

`generate_image` example

{
  "prompt": "1girl, solo, hatsune miku, vocaloid, long hair, twintails, smile, upper body, city night, neon lights, masterpiece, best quality, very aesthetic, absurdres",
  "width": 832,
  "height": 1216,
  "steps": 28,
  "guidance_scale": 5.0,
  "seed": 42
}

Add "image_path": "C:/path/to/source.png", "strength": 0.5 for image-to-image (output size follows the source).Add "loras": ["my_style.safetensors"], "lora_scales": [0.8] to apply LoRAs — they are applied per call; a call without loras runs on the bare checkpoint.

Set "render_type": "gpu" to abort instead of silently falling back to a slow CPU render when CUDA isn't available.

Models

Base model: cagliostrolab/animagine-xl-4.0, fetched from HuggingFace (cached in ~/.cache/huggingface).
Custom checkpoints: drop SDXL .safetensors files into checkpoints/ and reference them by filename.
LoRAs: drop .safetensors files into loras/. Multiple LoRAs can be combined with independent scales.

Outputs

Images are written to outputs/YYYY-MM-DD/anime_HHMMSS.png with a sidecar .json containing prompt, negative prompt, seed, size, steps, guidance, checkpoint, LoRAs and render type — enough to reproduce the image.

Prompt rules (short version)

Animagine XL 4.0 expects Danbooru-style comma-separated tags:

End with quality tags: masterpiece, best quality, very aesthetic, absurdres.
Start with subject count (1girl, 1boy, 2girls, ...).
Character tags should be followed by their series tag.
Aim for 8+ tags; order: subject → character → series → appearance → composition → environment → style → quality.
Use the default negative prompt unless you have a reason not to.

validate_prompt and optimize_prompt enforce these for you.

Development

pip install -e .
python -c "from anime_diffusion_mcp.server import mcp; print(mcp.name)"

Package layout:

src/anime_diffusion_mcp/
├── server.py        # FastMCP tools
├── prompt/          # tokenizer, classifier, validator, optimizer
├── diffusion/       # ImagePipeline (Diffusers wrapper, checkpoint/LoRA handling)
└── contracts/       # Pydantic schemas and error codes

License

MIT — see LICENSE.

Model by Cagliostro Research Lab. Built with FastMCP and Diffusers.

anime-diffusion-mcp