Aseprite MCP Tools

A Python MCP server that gives AI assistants full control over Aseprite for creating pixel art and animated sprites.

104 tools across 17 categories — canvas, drawing, layers, animation, palettes, effects, slices, tilemaps, exports, visual-feedback/analysis tools, and a raw Lua escape hatch. The tool set is designed so an LLM has everything it needs to produce *good* pixel art, not just primitives: shading ramps with hue shifting, ordered dithering, outlines, retro palette presets with quantization, onion-skin renders, and frame diffing for animation work.

Example: a swordsman, drawn and animated by Claude

Task 1 — "Draw me a pixel art of a swordsman."32×32 still, exported at 10×.

Task 2 — "…a sword slash attack sequence, from windup to follow-through."4-frame animation, exported with export_tag.

The same slash as a spritesheet (export_spritesheet): windup → extension → swing → follow-through.

Both were created end-to-end by Claude Fable 5 through this server's MCP tools — drawing, checking its own work with scaled `export_frame` previews and `render_onion_skin`, then exporting. The tasks recreate the benchmark from Draw Me a Swordsman by Lj Miranda, whose findings inspired this server's expanded toolset.

Tool Categories

Canvas

Drawing

All `_at` variants target a specific layer/frame and can create the cel on demand. Coordinates are sprite-global.

Text

Aseprite's Lua API has no text drawing, so glyphs are rasterised on the server and composited into the sprite. Two font backends are supported: bitmap sprite-sheet fonts (the right choice for pixel art — glyphs are already pixels and `size` scales them by whole numbers) and TrueType `.ttf`/`.otf` files, rendered without antialiasing unless you ask for it.

Fonts are discovered in `~/.aseprite-mcp/fonts`: a bitmap font is a directory containing `font.json` plus its sheet PNGs; a TrueType font is just the font file. Installed system fonts are listed too. `font` also accepts a direct path.

Call `measure_text` first when the layout depends on the text: it returns the same metrics `draw_text` will use, so a label can be centred or a plate sized in one pass.

measure_text(text="MODERATOR", font="minecraft", size=2, bold=1)
  -> width=115 height=15 advance_width=117 above_baseline=14 below_baseline=1 left_bearing=0

draw_text(filename="badge.aseprite", text="MODERATOR", x=64, y=17,
          font="minecraft", size=2, anchor="baseline", bold=1,
          color="#FFFFFF", shadow_color="#14237A")

Anchors are `topleft`/`top`/`topright`, `left`/`center`/`right`, `bottomleft`/`bottom`/`bottomright`, plus `baselineleft`/`baseline`/`baselineright` for pinning several labels to one baseline. Outline and shadow grow the stamp but never move the glyphs.

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": ["#...#", "#...#", ".#.#.", "..#.."]}
  }
}

Each sheet carries its own `ascent`, so sheets with different cell sizes still share a baseline — that is how a compact ASCII sheet and a taller accented sheet combine into one run. `origin` shifts the cell grid when the sheet has a margin, `ink_rule: "dark"` reads sheets that use an opaque white background to delimit variable-width glyph boxes, and `advance: "box"` takes the advance from the box rather than the ink. `overrides` replaces individual glyphs with hand-drawn rows, which is useful when a sheet ships a glyph that is off-centre or too tall to sit on the line.

Layers

Selection & Regions

Effects

The pixel-art toolbox: clean outlines, palette-respecting blends, and shading variants.

Animation

Palette

Transform

Slices

Tilemap

Export & Import

Inspection

Analysis & Visual Feedback

Batch-mode equivalents of what a human artist gets from the Aseprite UI.

Quality

Scene

Preview & Guide

Scripting

Recommended Workflow for LLMs

1. Plan the palette first: `generate_color_ramp` for each material (skin, armor, blade), or `apply_palette_preset` for a retro look.

2. Build in layers: background / body / equipment / effects, so parts can be animated and edited independently.

3. Draw coarse to fine: silhouette with `draw_rectangle_at` / `draw_ellipse_at` / `fill_area_at`, then refine with `draw_pixels_at`.

4. Look at your work: `export_frame` at 8×, inspect, fix, repeat. Use `get_color_stats` to keep the palette tight.

5. Shade with intent: `adjust_hsl` for shadow layers, `apply_dither_gradient` for blends, `outline_cel` for readability.

6. Animate with the cel tools: `propagate_cels`, then `tween_cel_positions_eased` / `oscillate_cel_positions`; verify with `render_onion_skin` and `compare_frames`; export with `export_tag`.

Docker Usage

Quick Start

Build and run the Docker image:

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

Or use the provided build scripts:

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

Using Docker Compose

# Production
docker-compose up aseprite-mcp

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

See DOCKER.md for detailed Docker setup instructions.

Optional: Install Aseprite via Steam

To have the container install Aseprite via SteamCMD at startup, provide Steam credentials:

# Create a .env with STEAM_USERNAME/STEAM_PASSWORD (and optional STEAM_GUARD_CODE)
# Then
docker run --rm -i --env-file .env aseprite-mcp:latest

If installed, the binary will be at `/opt/steamapps/common/Aseprite/aseprite` and `ASEPRITE_PATH` will be picked up automatically.

Local Installation

Prerequisites

• Python 3.13+
• `uv` package manager
• Aseprite (set `ASEPRITE_PATH` in `.env` if it is not on your PATH)

Installation:

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