Aseprite MCP

Aseprite MCP Tools

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

123 tools across 18 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, bounds and lint checks for animation work.

Examples

Cosy room (Opus 5.5)

An isometric bedroom at dusk with a girl doing her homework, animated as a lofi-style loop.
128×128, 16-frame loop, exported at 4×.

Swordsman: Fable 5 vs Opus 5.5

Fable 5 Opus 5.5

The benchmark swordsman, then a slash from windup to follow-through.
48×48, 4-frame slash. Opus 5.5 critiqued the Fable 5 sprite and redrew it at the same size.
48×48, 8-frame slash.

The Fable 5 tasks recreate the benchmark from Draw Me a Swordsman by Lj Miranda, whose findings inspired this server's expanded toolset.

Slime (Opus 5.5)

A green slime.
32×32 still, exported at 8×.

The slime bouncing to the right with squash and stretch.
43-frame animation, exported at 4×.

Swordsman vs. slime (Opus 5.5)

The swordsman slashes the slime, which flashes red, loses health and pops a damage number.
80×58, 15 frames, exported at 5×.

Related Projects

Aseprite Live – Watch an AI agent draw pixel art in Aseprite, live, in your browser

Tool Categories

Canvas

Drawing

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

draw_rows(filename="mug.aseprite", layer_name="mug", frame_index=1, x=4, y=2,
          rows=[".WWWW..",
                ".WWWWKK",
                ".WWWW.K",
                "..WW.K."],
          legend={"W": "#F4F4F4", "K": "#8B5A2B"}, outline="#1A1C2C")

. (or any character missing from the legend) leaves a pixel untouched; read_rows returns pixels in the same format, so an edit is read, change a few characters, draw again.

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.

Native filters run Aseprite's own engine commands on a layer and frame:

Animation

Palette

Transform

Slices

Tilemap

Export & Import

Inspection

Analysis & Visual Feedback

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

view_sprite is the drawing loop's eyes: it returns the picture as MCP image content, so the model sees its work without exporting a file and opening it, and works in clients that cannot read local files. Pick frames with "3", "1-4" or "1,3,6-8", layer_name to isolate one layer, and region="x,y,w,h" to zoom into a detail with rulers still in sprite coordinates.

Quality

Scene

Preview & Guide

The server also sends short pixel-art rules as MCP instructions when a client connects (silhouette first, one light direction, clean lines, check each pass), so the model gets them without calling anything.

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_rows.
4. Look at your work: view_sprite after every pass (region to zoom in), fix, repeat. Use get_color_stats to keep the palette tight and lint_sprite to catch stray and detached pixels.
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 view_sprite, compare_frames and get_bounds; export with export_animation or 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"
          ]
      }
  }
}