diivi/aseprite-mcp

What it is. A Python MCP server that lets an AI assistant (like Claude) drive the pixel-art editor Aseprite directly. Instead of the AI describing what it wants and a human doing the clicking, the AI itself can create sprites, draw pixels, animate frames, manage layers, apply effects, export files, and even run raw Lua scripts inside Aseprite — all through a set of 123 named tools organized into 18 categories.

How the pieces fit. The server exposes tools grouped by job — canvas setup, drawing, text, layers, selections, effects, animation, palettes, transforms, slices, tilemaps, export/import, inspection, analysis, quality checks, scene copying, a preview server, and a Lua escape hatch. The README emphasizes that the toolset was deliberately built so an AI can produce good pixel art, not just primitives: it includes shading ramps with hue shifting, ordered dithering, outlines, retro palette presets with quantization, onion-skin renders, frame diffing, bounds and lint checks for animation work.

What you can actually do with it (highlights, all grounded in the README):

Draw — pixels, lines, rectangles, circles, ellipses, polygons, paths, flood fills, gradients, isometric boxes, and an ASCII-art-style draw_rows tool that places pixels via character rows plus a color legend; read_rows returns pixels in that same compact format for read-edit-draw cycles.
Animate — frames, cels, tags, tweens with easing, sine-wave motion (bob/breath/hover), onion-skin rendering, frame diffing, and quality audits for animation consistency.
Palette work — read/set palettes, apply retro presets (gameboy, pico8, c64, cga, dawnbringer16, dawnbringer32, grayscale_4, monochrome), generate shading ramps, quantize to the nearest palette color.
Effects — outlines, color replacement, HSL adjustment, dithered gradients/patterns, plus native Aseprite filters (outline, hue/sat, brightness/contrast, invert, convolution matrices like blur/sharpen/edge/emboss).
Export & import — PNG/GIF/JPG, sprite sheets with JSON metadata, per-layer or per-tag export, animation as GIF or PNG sequences, importing a PNG as a layer, duplicating the sprite file.
Analysis & feedback — view_sprite returns an image of the frames to the model itself (zoomed, with pixel grid and coordinate rulers), so the AI sees its own work without exporting a file and opening it. There's also onion-skin rendering, frame diffing, bounding boxes, a sprite linter (detached/lone pixels), and color histograms to catch palette drift.
Text — Aseprite's Lua API has no text drawing, so the server rasterizes glyphs itself. Two font backends: bitmap sprite-sheet fonts (right for pixel art, whole-number scaling) and TrueType fonts, rendered without antialiasing unless requested. measure_text returns the same metrics draw_text uses, so AI can center labels without redrawing.
Scripting — run_lua_script executes arbitrary Aseprite Lua in batch mode as a last resort for anything not covered. The README warns: it runs unrestricted code on the host, so only pass scripts you trust.

Recommended workflow the README gives to AI models:

Plan the palette first (color ramps or retro presets).
Build in layers (background / body / equipment / effects) so parts animate independently.
Draw coarse to fine — silhouettes first, then refine with draw_rows.
Look at your work after every pass with view_sprite; use get_color_stats and lint_sprite to catch issues.
Shade deliberately — adjust_hsl for shadows, apply_dither_gradient for blends, outline_cel for readability.
Animate with cel tools — propagate_cels, then tweens with easing.

Example outputs shown in the README (all by AI models, demonstrating the toolset):

A 128×128, 16-frame isometric bedroom at dusk with a girl doing homework and a cat on a bookshelf, animated as a lofi-style loop.
A 48×48 swordsman benchmark (from Lj Miranda's "Draw Me a Swordsman" article, which inspired the expanded toolset): Fable 5 drew a 4-frame slash; Opus 5.5 critiqued the sprite and redrew it with an 8-frame slash.
A 32×32 green slime, plus a 43-frame bounce animation with squash and stretch.
A 80×58, 15-frame battle scene where the swordsman slashes the slime — it flashes red, loses health, pops a damage number.

Related project: Aseprite Live — watch an AI agent draw in Aseprite live in your browser.

In short: this is a bridge that turns Aseprite into a fully controllable drawing surface for AI assistants — complete with the kind of analysis and feedback tools human artists would use (onion skins, frame diffs, lints, histograms), so the AI can iteratively improve its own pixel art.