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

<b>Task 1</b> — <em>"Draw me a pixel art of a swordsman."</em>32×32 still, exported at 10×.
<b>Task 2</b> — <em>"…a sword slash attack sequence, from windup to follow-through."</em>4-frame animation, exported with <code>export_tag</code>.





The same slash as a spritesheet (<code>export_spritesheet</code>): 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

Category	Tools	Description
Canvas	6	Create sprites, manage layers/frames, set the active state
Drawing	14	Pixels, lines, rectangles, circles, ellipses, polygons, paths, fills, gradients
Text	3	Draw and measure text with bitmap sprite-sheet or TrueType fonts
Layers	7	Delete, rename, duplicate, reorder, blend modes, merge, flatten
Selection & Regions	4	Move, copy, and erase rectangular regions or colors
Effects	5	Outlines, color replacement, HSL adjustment, ordered dithering
Animation	24	Frames, cels, tags, tweening with easing, propagation
Palette	8	Get/set palettes, retro presets, color ramps, quantization, color modes
Transform	4	Flip, rotate, resize, crop
Slices	5	Named regions, 9-patch centers, pivot points
Tilemap	5	Tilemap layers, tileset editing, tile placement
Export & Import	7	PNG, GIF, sprite sheets, per-layer/per-tag export, image import
Inspection	3	Read pixels and sprite metadata
Analysis & Visual Feedback	3	Onion-skin renders, frame diffing, color statistics
Quality	4	Validate and sanitize animation consistency
Scene	1	Copy layers between sprite files
Preview & Guide	3	Local HTTP preview server, workflow guide
Scripting	1	Raw Lua escape hatch for anything not covered above

Canvas

Tool	Description
create_canvas	Create a new sprite with the given dimensions
add_layer	Add a new layer, optionally inside a named group
add_group	Add a new (optionally nested) group layer
add_frame	Append a new frame
set_frame	Set the active frame
set_frame_duration	Set one frame's duration in ms
set_layer	Set the active layer (optionally creating it)

Drawing

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

Tool	Description
draw_pixels	Plot individual pixels with per-pixel colors
draw_pixels_at	Plot pixels on a specific layer/frame
draw_line / draw_line_at	Lines with thickness
draw_rectangle / draw_rectangle_at	Outlined or filled rectangles
draw_circle / draw_circle_at	Outlined or filled circles
draw_ellipse_at	Outlined or filled ellipses with separate x/y radii
draw_polygon	Outlined or filled polygons from a point list
draw_path	Polyline through a point list with thickness
fill_area / fill_area_at	Paint-bucket flood fill
apply_gradient_rect	Smooth linear gradient fill in a rectangle

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.

Tool	Description
list_text_fonts	List the bitmap and TrueType fonts available to draw_text
measure_text	Width, height, advance and baseline extents — size a panel or centre a label without redrawing to find out
draw_text	Draw text with anchors, faux bold, outline, drop shadow and letter spacing

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