aseprite-mcp

Purpose

aseprite-mcp is a Python MCP server that gives AI assistants full control over Aseprite for creating pixel art and animated sprites. It exposes Aseprite's capabilities as MCP tools, enabling large language models to draw, inspect their own work, and export results.

Main capabilities

The server contains 104 tools across 17 categories, covering canvas, drawing, layers, animation, palettes, effects, slices, tilemaps, export, visual feedback/analysis tools, and a native Lua escape hatch.

The toolset is designed so that an LLM has everything needed to produce good pixel art, not just basic primitives, including: shading gradients with hue shifting, ordered dithering, outlining, retro palette presets with quantization, onion skin rendering, and frame diffing for animation work.

All _at variants target a specific layer/frame and can create cels as needed. Coordinates are sprite-global coordinates.

Text drawing

Aseprite's Lua API has no text drawing capability, so glyphs are rasterized server-side and then composited into the sprite. Two font backends are supported: bitmap sprite sheet fonts (the correct choice for pixel art—the glyphs are already pixels, and sizes are scaled by integer multiples) and TrueType .ttf/.otf files (rendered without antialiasing unless requested).

Fonts are discovered in ~/.aseprite-mcp/fonts : a bitmap font is a directory containing font.json and its sheet PNG; a TrueType font is just the font file itself. Installed system fonts are also listed.font also accepts direct paths.

When layout depends on text, call measure_textfirst: it returns the same metrics that draw_text will use, so labels can be centered in one pass or the backing plate sized in one pass.

Anchors include topleft/top/topright、left/center/right、bottomleft/bottom/bottomright, and baselineleft/baseline/baselineright, for pinning multiple labels to the same baseline. Outlines and shadows expand the stamp, but never move the glyphs.

Each font sheet carries its own ascent, so sheets with different cell sizes still share a baseline—this is how a compact ASCII sheet and a taller accented sheet combine into one run. When a sheet has margins,origin shifts the cell grid;ink_rule: "dark" reads sheets that use an opaque white background to delimit variable-width glyph boxes;advance: "box" takes the advance from the box instead of the ink.overrides replaces a single glyph with a hand-drawn row, which is useful when a sheet provides a glyph that is off-center or too tall to sit on the line.

Selections and regions

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

Export and import

Analysis and visual feedback

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

Preview and reference

Recommended workflow for LLMs

1. Plan the palette first: use generate_color_rampfor each material (skin, armor, blade), or use apply_palette_preset for a retro look.
2. Build in layers: background/body/gear/effects, so each part can be animated and edited independently.
3. Draw from coarse to fine: sketch the outline with draw_rectangle_at/draw_ellipse_at/fill_area_at , then refine with draw_pixels_at .
4. Look at your work: export export_frameat 8x, inspect, fix, repeat. Use get_color_stats to keep the palette tight.
5. Shade with intent: use adjust_hsl for shadow layers, use apply_dither_gradient For blending, use outline_cel to improve readability.
6. Use the cel tool for animation:propagate_cels, then tween_cel_positions_eased/oscillate_cel_positions; use render_onion_skin and compare_frames to verify; use export_tag to export.

Usage

Build and run the Docker image

Or use the provided build script:

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

Using Docker Compose

For detailed Docker setup instructions, see DOCKER.md.

Optional: Install Aseprite via Steam

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

If already installed, the binary will be located at /opt/steamapps/common/Aseprite/aseprite，ASEPRITE_PATH will be fetched automatically.

Local installation

Requires the uv package manager, Aseprite (if not in PATH, set .env in ASEPRITE_PATH), and an MCP server for interacting with the Aseprite API.

Use cases

Suitable for letting an AI assistant draw pixel art, create animated sprites via MCP tools, and use visual feedback tools for self-checking and exporting. The example in the project (a swordsman) was created entirely by Claude Fable through the server's MCP tools—drawing, using the scaled export_frame preview and render_onion_skin to check its own work, then exporting.

Limitations

Information not explicitly stated in the materials, such as fees, pricing, platforms, effects, or usage steps, is not provided at this time.