Animagine

Animagine MCP exposes fast MCP protocol and FastAPI REST endpoints to streamline prompt tooling, model management, and image generation for Animagine XL 4.0. It lets you connect AI agents or web apps to validate prompts, optimize prompts, manage models, and generate images with GPU acceleration.

How to use

You integrate an MCP client to access the Animagine MCP server through two interfaces: the MCP protocol for AI agents and the REST API for web or application usage. Use the MCP path when your workflow involves Claude Desktop, Cursor, or other MCP-compatible clients. Use the REST API when you’re building web apps, CLI tools, or mobile integrations. Start by configuring a client to point at the local server or a remote MCP endpoint, then use the available tools to validate, optimize, explain, load models, and generate images.

How to install

Prerequisites you’ll need before installation include a GPU-enabled system with CUDA support and Docker for the GPU-enabled setup, or Python 3.11+ for local installation. Ensure you have Docker and Docker Compose, the NVIDIA Container Toolkit, and a recent NVIDIA driver installed on your machine.

Option A: Docker (Recommended) provides GPU acceleration and a ready-to-run REST API on port 8000. The process creates necessary directories and preloads Animagine XL 4.0. Follow these steps exactly.

# Step 1: Clone the project
git clone https://github.com/gabrielalmir/mcp-animaginexl.git
cd mcp-animaginexl

# Step 2: Build and start the container
docker-compose up -d

# Step 3: Verify startup logs
docker-compose logs -f

# You should see startup messages indicating directories and the model were prepared and the server is running.

Access the services after the container starts. REST API documentation is available at http://localhost:8000/docs, with an alternative at http://localhost:8000/redoc. Health checks can be performed with curl http://localhost:8000/health.

Option B: REST API Only lets you run the API server without MCP protocol support. Install the package and start the API directly.

# Run the API server directly
pip install -e .
animagine-api

# API will be reachable at http://localhost:8000 with docs at /docs.

Option C: Local Installation lets you run the MCP server in a Python environment without Docker. This is suitable for development or systems without GPUs.

# Step 1: Clone and set up a virtual environment
git clone https://github.com/gabrielalmir/mcp-animaginexl.git
cd mcp-animaginexl
python -m venv .venv

# Step 2: Activate the virtual environment
# Linux/macOS
source .venv/bin/activate
# Windows
.venv\Scripts\activate

# Step 3: Install dependencies
pip install -e .

# Step 4: Start the MCP server
animagine-mcp

# Step 5: Verify it's running. The server exposes tools via FastMCP at the default endpoint.

Additional sections

MCP client configuration can be prepared as a .mcp.json file to connect your MCP client to Animagine. A local installation example uses the animagine-mcp command, with an optional environment block. A development setup shows how to run the server via Python, and a Docker-based approach demonstrates a containerized path.

Example local configuration for an MCP client that runs the Animagine MCP server directly: the key is the internal name animagine and the command animagine-mcp with an empty environment block.

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

Notes

This MCP server supports both MCP protocol and REST API interfaces, enabling flexible integration options. If you plan to run with GPUs, ensure CUDA is properly configured and that you expose the correct ports for REST access if using non-default ports.

Available tools

validate_prompt

Validates a prompt against Animagine XL rules and returns validity, issues, and suggestions.

optimize_prompt

Converts descriptive text into optimized tag-based prompts and returns the optimized prompt with suggested actions.

explain_prompt

Explains the effect and category of each prompt tag to help you understand the prompt composition.

list_models

Lists available checkpoints and LoRA assets that can be loaded into the generation pipeline.

load_checkpoint

Pre-loads a selected checkpoint into GPU memory for faster reuse during generation.

unload_loras

Removes all LoRA weights from the currently loaded generation pipeline.

generate_image

Generates an image from a prompt using the configured model and optional LoRA settings.

generate_image_from_image

Performs image-to-image transformation using a provided input image and a prompt.