diivi/aseprite-mcp

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
| 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.