Skip to main content
Glama
gabrielalmir

Animagine MCP

by gabrielalmir
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Animagine MCP

FastMCP server for the Animagine XL 4.0 image generation experience, providing prompt validation, optimization, explanation, and checkpoint/LoRA management tools.

For AI Agents: This repository includes comprehensive markdown documentation in 02-behavior/, 03-contracts/, 04-quality/, and 05-implementation/ directories. These files contain detailed specifications, behavior rules, prompt taxonomies, and implementation guides optimized for AI agent consumption. If you're building AI-powered workflows or need structured guidance for prompt engineering, check out these resources.

For Humans: Welcome! A few friendly reminders:

  • Do not commit AI agent files (.cursor/, .claude/, .copilot/, etc.) — these are already in .gitignore

  • Be respectful in discussions — we're all here to learn and build together

  • Help each other — share your knowledge, ask questions, and contribute back

Let's create something amazing together! 🎨

Table of Contents

Overview

Animagine MCP exposes powerful tools through FastMCP (MCP protocol) and FastAPI (REST API):

  • Prompt Tools: validate_prompt, optimize_prompt, explain_prompt

  • Model Tools: list_models, load_checkpoint, unload_loras

  • Generation Tools: generate_image, generate_image_from_image

Key features:

  • Dual API support: Use MCP protocol for AI agents or REST API for web/app integration

  • Normalizes prompts for consistent structure, category coverage, and tag ordering

  • Integrates with local checkpoint and LoRA assets

  • GPU-accelerated image generation with CUDA support

  • Docker-ready with comprehensive GPU configuration

  • Interactive API documentation with Swagger UI

Choose Your Interface

Interface

Best For

Port

MCP Server

Claude Desktop, Cursor, other MCP clients

stdio

REST API

Web applications, CLI tools, mobile apps

8000

REPL

Interactive testing and development

stdin/stdout

Note: This platform can generate NSFW material. Choosing to do so and owning the resulting content is the caller's responsibility.

Quick Start Guide

Option 1: Docker (Recommended)

The fastest way to get started with GPU acceleration.

What's Included

  • Automatic setup: Directories (checkpoints/, loras/, outputs/) are created automatically

  • Pre-downloaded model: Animagine XL 4.0 (~6GB) is downloaded during build

  • GPU acceleration: CUDA 12.1 with optimized PyTorch

  • REST API: FastAPI server on port 8000 with interactive documentation

Prerequisites

  • Docker and Docker Compose installed

  • NVIDIA GPU with drivers installed (verify with nvidia-smi)

  • NVIDIA Container Toolkit (installation guide)

  • ~15GB disk space (for Docker image + model)

Steps

Step 1: Clone the repository

git clone https://github.com/gabrielalmir/mcp-animaginexl.git cd mcp-animaginexl

Step 2: Build and start the container

docker-compose up -d

Note: First build downloads Animagine XL 4.0 (~6GB) and may take 10-20 minutes depending on your connection. Subsequent builds use cached layers.

Step 3: Verify startup (watch logs)

docker-compose logs -f

You should see:

=== Animagine MCP Startup === Checking directories... ✓ /app/checkpoints ✓ /app/loras ✓ /app/outputs Verifying Animagine XL 4.0 model... ✓ Model already cached Checking GPU status... ✓ GPU Available: NVIDIA GeForce RTX 3090 ✓ CUDA Version: 12.1 === Starting Animagine MCP Server ===

Step 4: Access the services

REST API:

MCP Server (for Claude Desktop, Cursor, etc.):

Quick Docker Commands

Command

Description

docker-compose up -d

Start the server

docker-compose down

Stop the server

docker-compose logs -f

View logs

docker-compose exec animagine-mcp bash

Shell access

docker-compose build --no-cache

Rebuild from scratch

Environment Variables

Variable

Description

Default

SKIP_MODEL_DOWNLOAD

Skip model verification on startup

false

Option 1b: REST API Only

If you only want to use the REST API without MCP protocol support:

# Run the API server directly (requires local Python 3.11+) pip install -e . animagine-api

The API will be available at http://localhost:8000 with full documentation at /docs.

Option 2: Local Installation

For development or systems without Docker.

Prerequisites

  • Python >= 3.11

  • GPU with CUDA support (recommended)

  • git and pip

Steps

Step 1: Clone and create virtual environment

git clone https://github.com/gabrielalmir/mcp-animaginexl.git cd mcp-animaginexl python -m venv .venv

Step 2: Activate the virtual environment

Windows:

.venv\Scripts\activate

Linux/macOS:

source .venv/bin/activate

Step 3: Install dependencies

pip install -e .

Step 4: Start the MCP server

animagine-mcp

Step 5: Verify it's running

The server is now exposing tools via FastMCP at the default endpoint.

Option 3: Interactive REPL (Testing)

Test MCP tools interactively without running the full server.

Quick Start

# From project root (no installation needed) python repl.py # Or if installed animagine-repl

REPL Interface

╔═══════════════════════════════════════════════════════════════════╗ ║ Animagine MCP REPL ║ ║ Interactive Tool Testing ║ ╠═══════════════════════════════════════════════════════════════════╣ ║ Commands: ║ ║ help - Show help message ║ ║ tools - List available tools ║ ║ tool <name> - Show tool details ║ ║ exit - Exit the REPL ║ ╚═══════════════════════════════════════════════════════════════════╝ animagine> validate_prompt("1girl, blue hair, masterpiece") { "is_valid": true, "issues": [], "suggestions": [...] } animagine> optimize_prompt(description="anime girl in a garden") { "optimized_prompt": "1girl, solo, garden, flowers, ..., masterpiece, best quality", "actions": [...] }

CLI Options

python repl.py --list # List all tools python repl.py --tool validate # Show tool details python repl.py -e "list_models()" # Execute single command python repl.py --debug # Enable debug mode

MCP Client Configuration

To connect an MCP client (like Claude Desktop, VS Code, or other MCP-compatible tools) to this server, create a .mcp.json configuration file.

Example .mcp.json

For local installation:

{ "mcpServers": { "animagine": { "command": "animagine-mcp", "env": {} } } }

For development (running from source):

{ "mcpServers": { "animagine": { "command": "python", "args": ["-m", "animagine_mcp.server"], "cwd": "/path/to/mcp-animaginexl", "env": { "PYTHONPATH": "/path/to/mcp-animaginexl/src" } } } }

For Docker:

{ "mcpServers": { "animagine": { "command": "docker", "args": ["exec", "-i", "animagine-mcp-server", "animagine-mcp"], "env": {} } } }

Windows example:

{ "mcpServers": { "animagine": { "command": "python", "args": ["-m", "animagine_mcp.server"], "cwd": "C:\\Users\\YourName\\Projects\\mcp-animaginexl", "env": { "PYTHONPATH": "C:\\Users\\YourName\\Projects\\mcp-animaginexl\\src" } } } }

Configuration Options

Field

Description

command

Executable to run (animagine-mcp, python, or docker)

args

Command line arguments

cwd

Working directory (optional)

env

Environment variables (optional)

Where to Place .mcp.json

Depending on your MCP client:

  • Claude Desktop: ~/.config/claude/mcp.json (Linux/Mac) or %APPDATA%\Claude\mcp.json (Windows)

  • VS Code: Project root or workspace settings

  • Other clients: Check client documentation

Core Tools

The same powerful tools are available through both MCP protocol and REST API:

Prompt Tools

Tool

MCP Call

REST Endpoint

Description

validate_prompt

validate_prompt(...)

POST /api/v1/validate-prompt

Validates prompt against Animagine XL rules

optimize_prompt

optimize_prompt(...)

POST /api/v1/optimize-prompt

Restructures and optimizes prompt tags

explain_prompt

explain_prompt(...)

POST /api/v1/explain-prompt

Explains each tag's category and effect

Model Tools

Tool

MCP Call

REST Endpoint

Description

list_models

list_models()

GET /api/v1/models

Lists available checkpoints and LoRAs

load_checkpoint

load_checkpoint(...)

POST /api/v1/load-checkpoint

Pre-loads a checkpoint to GPU memory

unload_loras

unload_loras()

POST /api/v1/unload-loras

Removes all LoRA weights from pipeline

Generation Tools

Tool

MCP Call

REST Endpoint

Description

generate_image

generate_image(...)

POST /api/v1/generate

Generates image from prompt

generate_image_from_image

generate_image_from_image(...)

POST /api/v1/generate-img2img

Image-to-image transformation

Using the REST API

For detailed REST API documentation, see API.md which includes:

  • Full endpoint reference

  • Request/response examples

  • cURL examples

  • Python client examples

  • Performance tuning guide

Quick start:

# List available models curl http://localhost:8000/api/v1/models # Generate an image curl -X POST http://localhost:8000/api/v1/generate \ -H "Content-Type: application/json" \ -d '{ "prompt": "masterpiece, best quality, anime girl", "steps": 28 }' # Interactive documentation open http://localhost:8000/docs

Usage Examples

Example 1: Validate a Prompt

# Validate before generation result = validate_prompt( prompt="1girl, blue hair, school uniform", width=832, height=1216 ) print(result) # Shows issues and suggestions

Example 2: Optimize a Natural Language Description

# Convert description to optimized tags result = optimize_prompt( description="A beautiful anime girl with long silver hair standing in a flower field at sunset" ) print(result["optimized_prompt"])

Example 3: Generate an Image

# Generate with default settings result = generate_image( prompt="1girl, silver hair, flower field, sunset, masterpiece, best quality", steps=28, guidance_scale=5.0 ) print(f"Image saved to: {result['image_path']}")

Example 4: Use Custom Checkpoint and LoRA

# List available models first models = list_models() print(models["checkpoints"]) print(models["loras"]) # Generate with custom models result = generate_image( prompt="1girl, anime style, masterpiece", checkpoint="custom_model.safetensors", loras=["style_lora.safetensors"], lora_scales=[0.8] )

REST API

For full REST API documentation with detailed examples, see API.md.

Quick Reference

Base URL: http://localhost:8000/api/v1

Interactive Documentation: http://localhost:8000/docs

Common Endpoints:

  • POST /validate-prompt - Validate a prompt

  • POST /optimize-prompt - Optimize a prompt

  • POST /explain-prompt - Explain prompt tags

  • GET /models - List available models

  • POST /load-checkpoint - Load a checkpoint

  • POST /generate - Generate an image

  • POST /generate-img2img - Transform an image

Example: Generate an image via REST API

curl -X POST http://localhost:8000/api/v1/generate \ -H "Content-Type: application/json" \ -d '{ "prompt": "masterpiece, best quality, anime girl, blue hair", "steps": 28, "guidance_scale": 5.0 }'

Advanced Guide

GPU Acceleration

GPU acceleration provides 10-50x faster generation compared to CPU.

Requirements

  • NVIDIA GPU (GTX 1060 or newer recommended)

  • CUDA drivers installed

  • For Docker: NVIDIA Container Runtime

Verify GPU Setup

# Check NVIDIA driver nvidia-smi # Check PyTorch GPU support (in container or local env) python -c "import torch; print(torch.cuda.is_available())"

GPU Performance Tips

  1. Pre-load checkpoints to reduce first-generation latency:

    load_checkpoint("default") # Pre-loads Animagine XL 4.0

  2. Monitor GPU usage during generation:

    watch -n 1 nvidia-smi

  3. Optimize memory for large models:

    # Set in environment export PYTORCH_CUDA_ALLOC_CONF="max_split_size_mb:512"

See GPU_SETUP.md for detailed GPU configuration.

Docker Configuration

Three Docker Compose configurations are available:

File

Description

Use Case

docker-compose.yml

GPU-enabled (default)

Production with NVIDIA GPU

docker-compose.gpu.yml

Advanced GPU settings

Multi-GPU, profiling

docker-compose.cpu.yml

CPU-only fallback

Development, no GPU

Switching Configurations

# GPU (default) docker-compose up -d # Advanced GPU docker-compose -f docker-compose.gpu.yml up -d # CPU-only docker-compose -f docker-compose.cpu.yml up -d

Custom Port

Edit docker-compose.yml:

ports: - "8001:8000" # Change 8001 to desired port

Resource Limits

deploy: resources: limits: memory: 8G # Increase for larger models

See DOCKER.md for comprehensive Docker documentation.

Model Management

Adding Checkpoints

Place .safetensors or .ckpt files in ./checkpoints/:

cp my_model.safetensors ./checkpoints/

Adding LoRAs

Place LoRA files in ./loras/:

cp my_lora.safetensors ./loras/

Verifying Models

models = list_models() print("Checkpoints:", models["checkpoints"]) print("LoRAs:", models["loras"]) print("Currently loaded:", models["currently_loaded"])

Environment Variables

Variable

Description

Default

CUDA_VISIBLE_DEVICES

GPU device ID(s)

0

TORCH_CUDNN_BENCHMARK

Enable cuDNN auto-tuner

1

PYTORCH_CUDA_ALLOC_CONF

Memory allocation config

max_split_size_mb:512

HF_HOME

Hugging Face cache directory

~/.cache/huggingface

HF_HUB_DISABLE_TELEMETRY

Disable HF telemetry

1

Setting Variables

Local:

export CUDA_VISIBLE_DEVICES=0 animagine-mcp

Docker (in docker-compose.yml):

environment: CUDA_VISIBLE_DEVICES: "0,1" # Use GPUs 0 and 1

Performance Optimization

Recommended Settings by GPU

GPU

VRAM

Recommended Steps

Batch Size

RTX 3060

12GB

28

1

RTX 3080

10GB

28

1

RTX 3090

24GB

28-50

1-2

RTX 4090

24GB

28-50

2-4

A100

40GB+

50+

4+

Speed vs Quality Trade-offs

Setting

Speed

Quality

steps=20

Fast

Good

steps=28

Balanced

Great

steps=50

Slow

Excellent

Using LCM LoRA for Speed

# 4-8x faster generation with LCM result = generate_image( prompt="1girl, masterpiece", loras=["custom_lora.safetensors"], steps=8, # Reduced from 28 guidance_scale=1.5 # Reduced from 5.0 )

AI Agent Resources

This repository includes comprehensive documentation optimized for AI agents and automated workflows.

Documentation Structure

Directory

Purpose

Key Files

02-behavior/

Model behavior specifications

model-behavior-spec.md, prompt-rulebook.md, prompt-taxonomy.yaml

03-contracts/

Interface contracts and schemas

mcp-interface-contract.md, config-defaults-spec.md, error-handling-spec.md

04-quality/

Quality guidelines and strategies

quality-evaluation-guide.md, negative-prompt-strategy.md, prompt-cookbook.md

05-implementation/

Implementation guides

implementation-guide.md, mcp-tooling-notes.md

For AI Agent Developers

These resources are designed for:

  • Prompt Engineering: Detailed taxonomy and rules for Animagine XL 4.0 prompts

  • Automated Pipelines: Structured contracts for integrating with CI/CD or batch processing

  • Quality Assurance: Evaluation criteria and negative prompt strategies

  • MCP Integration: Interface specifications for building MCP-compatible clients

Quick Links

# View behavior specifications cat 02-behavior/model-behavior-spec.md # View prompt rules and taxonomy cat 02-behavior/prompt-rulebook.md cat 02-behavior/prompt-taxonomy.yaml # View MCP interface contract cat 03-contracts/mcp-interface-contract.md # View quality guidelines cat 04-quality/prompt-cookbook.md

Using with AI Coding Assistants

When using AI coding assistants (Claude, Cursor, Copilot, etc.), you can reference these docs:

"Read 02-behavior/prompt-rulebook.md and help me create a valid Animagine prompt" "Based on 03-contracts/mcp-interface-contract.md, implement a client for this MCP" "Use 04-quality/negative-prompt-strategy.md to improve my negative prompts"

Repository Layout

mcp-animaginexl/ ├── src/animagine_mcp/ # Core package │ ├── contracts/ # Data schemas and errors │ ├── diffusion/ # Diffusion pipeline wrapper │ ├── prompt/ # Prompt processing tools │ ├── server.py # FastMCP server definition │ └── repl.py # Interactive REPL module ├── checkpoints/ # Model checkpoints (.safetensors) [auto-created] ├── loras/ # LoRA modifiers [auto-created] ├── outputs/ # Generated images [auto-created] ├── 02-behavior/ # Behavior specifications ├── 03-contracts/ # Interface contracts ├── 04-quality/ # Quality guidelines ├── 05-implementation/ # Implementation notes ├── .mcp.json.example # MCP client config template ├── Dockerfile # GPU-optimized container ├── docker-entrypoint.sh # Container startup script ├── docker-compose.yml # Default GPU config ├── docker-compose.gpu.yml # Advanced GPU config ├── docker-compose.cpu.yml # CPU-only fallback ├── repl.py # Interactive REPL (run directly) ├── pyproject.toml # Project metadata └── README.md # This file

Contributors Guide

We welcome contributions! Here's how to get started.

Development Setup

Step 1: Fork and clone

git clone https://github.com/YOUR_USERNAME/mcp-animaginexl.git cd mcp-animaginexl

Step 2: Create development environment

python -m venv .venv source .venv/bin/activate # or .venv\Scripts\activate on Windows

Step 3: Install with development dependencies

pip install -e ".[dev]"

Step 4: Create a feature branch

git checkout -b feature/your-feature-name

Code Style

We follow these conventions:

Python Style

  • Formatter: black with default settings

  • Linter: ruff for fast linting

  • Type hints: Required for all public functions

  • Docstrings: Google style for all public APIs

Run Formatting

# Format code black src/ # Lint code ruff check src/ # Fix auto-fixable issues ruff check --fix src/

Pre-commit (Recommended)

# Install pre-commit hooks pip install pre-commit pre-commit install # Run on all files pre-commit run --all-files

Pull Request Process

1. Before Submitting

  • Code follows the style guide

  • Tests pass locally

  • Documentation updated (if applicable)

  • Commit messages are clear and descriptive

2. PR Template

Use this template for your PR description:

## Summary Brief description of changes. ## Changes - Change 1 - Change 2 ## Testing How was this tested? ## Related Issues Fixes #123

3. Review Process

  1. Submit PR to main branch

  2. Automated checks run (linting, tests)

  3. Maintainer reviews code

  4. Address feedback if any

  5. PR merged after approval

4. Commit Message Format

type: short description Longer description if needed. Fixes #123

Types: feat, fix, docs, style, refactor, test, chore

Examples:

feat: add batch generation support fix: resolve CUDA OOM error with large images docs: update GPU setup instructions

Testing Guidelines

Running Tests

# Run all tests pytest tests/ # Run with coverage pytest tests/ --cov=src/animagine_mcp # Run specific test file pytest tests/test_prompt.py

Writing Tests

# tests/test_prompt.py import pytest from animagine_mcp.prompt import validate_prompt def test_validate_prompt_basic(): """Test basic prompt validation.""" result = validate_prompt("1girl, blue hair, masterpiece") assert result.is_valid assert len(result.issues) == 0 def test_validate_prompt_missing_quality(): """Test validation catches missing quality tags.""" result = validate_prompt("1girl, blue hair") assert not result.is_valid assert any("quality" in issue.lower() for issue in result.issues)

Test Categories

Category

Description

Location

Unit

Individual functions

tests/unit/

Integration

Component interaction

tests/integration/

E2E

Full workflow

tests/e2e/

Areas for Contribution

Looking for something to work on? Here are some areas:

Good First Issues

  • Documentation improvements

  • Adding test coverage

  • Fixing typos or clarifying comments

Feature Ideas

  • Additional prompt optimization strategies

  • New LoRA management features

  • Performance benchmarking tools

  • Web UI frontend

Documentation

  • Tutorials for specific use cases

  • Video walkthroughs

  • Translated documentation

Support

Getting Help

  1. Check existing issues: Search GitHub Issues

  2. Read documentation: Check DOCKER.md, GPU_SETUP.md, and this README

  3. Open new issue: Include:

    • Description of the problem

    • Steps to reproduce

    • Expected vs actual behavior

    • System info (OS, GPU, Python version)

    • Relevant logs (omit sensitive content)

Community

  • GitHub Discussions for questions

  • Issues for bugs and feature requests

License

This project is licensed under the terms specified in LICENSE.

Acknowledgments

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gabrielalmir/mcp-animaginexl'

If you have feedback or need assistance with the MCP directory API, please join our Discord server