DOCSEARCHbyAlgolia
Submit Docs

Aseprite MCP Server

repository·main·Indexed 43 days ago

https://github.com/diivi/aseprite-mcp

A Python-based Model Context Protocol (MCP) server that provides AI assistants with deep integration and control over Aseprite. It features 104 tools across 17 categories for automated pixel art and animation, including full canvas control, advanced animation tweening, palette quantization, tilemap management, and a raw Lua escape hatch for custom scripting.

Tokens
6K
Snippets
13
Records
32
Agent score
62%

What's inside Aseprite MCP

  1. Overview of Aseprite MCP Tools

    main

    Aseprite MCP Tools is a Python-based Model Context Protocol (MCP) server that enables AI assistants to control Aseprite. It provides a comprehensive set of tools designed for high-quality pixel art and animation creation, moving beyond simple primitives to support advanced techniques like shading ramps, dithering, and onion-skinning.

    Key capabilities include:

    • Full Canvas Control: Drawing, text, and layer management.
    • Advanced Animation: Frame diffing, onion-skin rendering, and animation-specific exports.
    • Artistic Tools: Palette quantization, retro presets, and effects like outlines and dithering.
    • Workflow Tools: Selection, regions, slices, tilemaps, and a raw Lua escape hatch for custom scripting.

  2. Tool Categories in Aseprite MCP

    main

    The server exposes 104 tools organized into 17 functional categories. An AI assistant can use these categories to perform complex workflows such as drawing a character, animating its movements, and exporting the final result as a spritesheet.

    Available Tool Categories:

    • Canvas
    • Drawing
    • Text
    • Layers
    • Selection & Regions
    • Effects
    • Animation
    • Palette
    • Transform
    • Slices
    • Tilemaps
    • Exports
    • Visual-feedback/analysis tools
    • Raw Lua escape hatch

  3. Build the Aseprite MCP Docker image

    main

    You can build the Docker image using the provided platform-specific scripts or by running a manual Docker build command. The image is based on the Homebrew Docker image and includes Python 3.13 and uv.

    # Using provided script (Linux/macOS)
./build-docker.sh

# Or manually
docker build -t aseprite-mcp:latest .

  4. Run Aseprite MCP via Docker

    main

    You can run the Aseprite MCP server using Docker.

    Quick Start

    Build and run the image directly:

    docker build -t aseprite-mcp:latest .
docker run -it --rm aseprite-mcp:latest

    Alternatively, use the provided build scripts:

    • Linux/macOS: chmod +x build-docker.sh && ./build-docker.sh
    • Windows: .\build-docker.ps1

    Docker Compose

    Use Docker Compose for production or development profiles:

    # Production
docker-compose up aseprite-mcp

# Development mode
docker-compose --profile dev up aseprite-mcp-dev

    Installing Aseprite via SteamCMD

    To have the container automatically install Aseprite via SteamCMD at startup, provide your Steam credentials in a .env file containing STEAM_USERNAME and STEAM_PASSWORD (and optionally STEAM_GUARD_CODE).

    docker run --rm -i --env-file .env aseprite-mcp:latest

    If installed, the binary is located at /opt/steamapps/common/Aseprite/aseprite and ASEPRITE_PATH is configured automatically.

  5. Configure Aseprite MCP in an MCP Client

    main

    To integrate the Dockerized Aseprite MCP server into an MCP-compatible client, add the following configuration to your client's settings. This uses the docker run command to execute the server in an interactive, ephemeral container.

    {
  "mcpServers": {
    "aseprite": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "aseprite-mcp:latest"
      ]
    }
  }
}

  6. Manage Aseprite MCP with Docker Compose

    main

    Docker Compose can be used to manage the container for production or development environments.

    • Production: Standard startup.
    • Development: Uses the dev profile to start the aseprite-mcp-dev service.
    # Production
docker-compose up aseprite-mcp

# Development
docker-compose --profile dev up aseprite-mcp-dev

  7. Local Installation of Aseprite MCP

    main

    To install Aseprite MCP locally, ensure you meet the following prerequisites:

    • **Python 3.13+$
    • uv package manager
    • Aseprite installed (If Aseprite is not in your system PATH, you must set the ASEPRITE_PATH environment variable in a .env file).

    To integrate with an MCP client (like Claude Desktop), add the following configuration to your mcpServers settings. Replace /path/to/repo with the actual absolute path to the repository.

    Note: The command uses uv to run the aseprite_mcp module directly.

    {
  "mcpServers": {
      "aseprite": {
          "command": "/opt/homebrew/bin/uv",
          "args": [
              "--directory",
              "/path/to/repo",
              "run",
              "-m",
              "aseprite_mcp"
          ]
      }
  }
}

  8. Recommended Workflow for LLMs using Aseprite MCP

    main

    When using an LLM to generate pixel art via Aseprite MCP, follow this structured workflow to ensure cohesive results:

    1. Plan the palette first: Use generate_color_ramp for specific materials (e.g., skin, armor, blade) or apply_palette_preset for established retro styles.
    2. Build in layers: Organize by background / body / equipment / effects to allow independent animation and editing.
    3. Draw coarse to fine: Start with silhouettes using draw_rectangle_at, draw_ellipse_at, or fill_area_at, then refine details with draw_pixels_at.
    4. Look at your work: Use export_frame at 8× magnification to inspect and fix details. Use get_color_stats to maintain palette consistency.
    5. Shade with intent: Use adjust_hsl for shadow layers, apply_dither_gradient for color blends, and outline_cel to improve readability.
    6. Animate with cel tools: Use propagate_cels, then apply motion with tween_cel_positions_eased or oscillate_cel_positions. Verify animation with render_onion_skin and compare_frames, then export using export_tag.

  9. Run the Aseprite MCP container

    main

    Use the following commands to run the container in different modes:

    • Basic run: Starts the container and removes it upon exit.
    • Development mode: Mounts the current working directory to /app inside the container, allowing for live code changes.
    • Interactive shell: Overrides the entrypoint to provide a Bash shell inside the container.
    # Basic run
docker run -it --rm aseprite-mcp:latest

# Development mode (with volume mount)
docker run -it --rm -v $(pwd):/app aseprite-mcp:latest

# Interactive shell
docker run -it --rm --entrypoint /bin/bash aseprite-mcp:latest

  10. Install Aseprite via SteamCMD in Docker

    main

    The image includes SteamCMD, allowing you to install the official Aseprite binary at container startup if you own it on Steam.

    To use this, you must provide your Steam credentials via environment variables. It is highly recommended to use an --env-file to avoid exposing credentials in your command history.

    Upon successful installation, the binary is located at /opt/steamapps/common/Aseprite/aseprite and the ASEPRITE_PATH environment variable is automatically configured.

    # Windows PowerShell: Using a .env file (Recommended)
docker run --rm -i --env-file .env aseprite-mcp:latest

# Passing credentials inline (Not recommended for security)
docker run --rm -i -e STEAM_USERNAME=you -e STEAM_PASSWORD=secret aseprite-mcp:latest

  11. Configure bitmap font JSON

    main

    Bitmap fonts are defined via a font.json file. This allows combining multiple sheets (e.g., a compact ASCII sheet and a taller accented sheet) by sharing a common baseline via the ascent property.

    Key Fields:

    • name: Font identifier.
    • letter_gap: Space between letters.
    • space_width: Width of the space character.
    • sheets: Array of sheet objects containing file, cell_w, cell_h, ascent, and chars (mapping glyphs to rows).
    • overrides: Replaces specific glyphs with hand-drawn rows (useful for fixing off-center glyphs).
    • ink_rule: "dark": Reads sheets using an opaque white background to delimit variable-width glyph boxes.
    • advance: "box": Uses the box width for character advancement instead of the ink.

    Example font.json:

    {
  "name": "my-font",
  "letter_gap": 1,
  "space_width": 3,
  "sheets": [{
    "file": "sheet.png",
    "cell_w": 8, "cell_h": 8,
    "ascent": 7,
    "chars": [" !\"#$%&'()*+,-./", "0123456789:;<=>?"]
  }],
  "overrides": {
    "86": {"ascent": 7, "rows": ["#...#", "#...#", ".#.#.", "..#.."]}
  }
}
    {
  "name": "my-font",
  "letter_gap": 1,
  "space_width": 3,
  "sheets": [{
    "file": "sheet.png",
    "cell_w": 8, "cell_h": 8,
    "ascent": 7,
    "chars": [" !\"#$%&'()*+,-./", "0123456789:;<=>?"]
  }],
  "overrides": {
    "86": {"ascent": 7, "rows": ["#...#", "#...#", ".#.#.", "..#.."]}
  }
}

  12. Run the Aseprite MCP server via CLI

    main

    The aseprite-mcp package can be executed as a standalone module to start the Model Context Protocol (MCP) server using the stdio transport layer. This allows an MCP client (like Claude Desktop) to communicate with Aseprite through standard input/output.

    To run the server, use the following command in your terminal:

    python -m aseprite_mcp