MCP server for the Aseprite pixel art editor. Enables AI assistants to create sprites, draw pixel art, manage layers/frames/palettes, create animations, and export assets through the Model Context Protocol.
How It Works
AI Assistant ←→ MCP Server (Node.js) ←→ Aseprite (batch mode + Lua scripting)
The server spawns Aseprite in batch mode (-b) with Lua scripts that perform operations and return JSON results via stdout.
Built for vision models
The server is designed so a model can see and iterate on its own art:
render_sprite returns an upscaled, pixel-crisp PNG as MCP image content (single frame or an all-frames strip) so the model can check silhouettes, contrast and animation flow. showGrid overlays pixel boundaries, region zooms in on a detail, and outputPath keeps the render for before/after comparison.
draw_grid paints a whole region from rows of characters plus a legend, the natural way to compose a sprite in one call.
get_canvas returns the same rows + legend format, so read → edit → write round-trips cleanly.
Server instructions describe the recommended create → draw → look → refine loop and pixel-art craft guidelines.
Quickstart
git clone https://github.com/Vollkorn-Games/aseprite-mcp.git
cd aseprite-mcp
pnpm install
pnpm build
Installation
Claude Code
claude mcp add aseprite-mcp -- node /path/to/aseprite-mcp/build/index.js
Aseprite is auto-detected from common install locations (Steam, /usr/bin, /Applications, etc.). Set ASEPRITE_PATH only if auto-detection fails.
Streamable HTTP (stateless)
The server also speaks the MCP Streamable HTTP transport (spec 2025-11-25) in stateless mode: every request gets a fresh server instance, no Mcp-Session-Id is issued, and requests can be load-balanced across processes.
claude mcp add --transport http aseprite-mcp http://127.0.0.1:3000/mcp
The server binds to 127.0.0.1 by default. Set MCP_HOST=0.0.0.0 to expose it on the network — put it behind an authenticating reverse proxy if you do, as the server has no built-in auth.
Requirements
Node.js >= 18.0.0
Aseprite >= 1.2.10 (with Lua scripting support)
pnpm (package manager)
Environment Variables
Variable
Description
ASEPRITE_PATH
Path to the Aseprite executable (auto-detected)
DEBUG
Set to true for verbose logging
MCP_TOOLSETS
Comma-separated list of tool categories to expose
MCP_EXCLUDE_TOOLS
Comma-separated list of tool names to exclude
MCP_READ_ONLY
Set to true to expose only read-only tools
MCP_TRANSPORT
stdio (default) or http (stateless Streamable HTTP)
MCP_PORT
HTTP port (default 3000, http transport only)
MCP_HOST
HTTP bind address (default 127.0.0.1)
MCP_PATH
HTTP endpoint path (default /mcp)
68 Tools Across 14 Categories
Sprite Management (5 tools)
Tool
Description
create_sprite
Create a new sprite with width, height, color mode
open_sprite
Open an existing sprite file and return metadata
get_sprite_info
Get detailed metadata (layers, frames, tags, palette)
save_sprite
Save sprite to file
resize_sprite
Resize sprite dimensions
Layer Operations (5 tools)
Tool
Description
add_layer
Add a new layer (normal or group)
remove_layer
Remove a layer by name or index
set_layer_properties
Set name, opacity, blend mode, visibility
list_layers
List all layers with metadata
flatten_layers
Flatten all layers into one
Frame & Animation (8 tools)
Tool
Description
add_frame
Add new frame (empty or duplicate)
remove_frame
Remove frame by number
set_frame_duration
Set frame duration in seconds
list_frames
List all frames with durations
reorder_frames
Reverse frame order within a range
duplicate_frame
Clone a frame with all cel content
add_frames
Bulk add multiple empty frames at once
set_frame_durations
Set durations for multiple frames
Drawing Operations (15 tools)
Tool
Description
draw_pixel
Set a single pixel color
draw_pixels
Set multiple pixels at once (batch)
erase_pixels
Erase points and/or a rectangle to transparent
draw_line
Draw line between two points
draw_rect
Draw rectangle (filled or outline)
draw_ellipse
Draw ellipse (filled or outline)
flood_fill
Flood fill from a point with a color
draw_image
Paste an external PNG onto a layer
draw_circle
Draw circle (filled or outline)
replace_color
Replace all pixels of one color with another
outline
Add outline around non-transparent pixels
get_pixels
Read pixel colors from a canvas region
draw_polygon
Draw polygon (filled or outline) from points
get_canvas
Dump full canvas as 2D hex color grid
draw_grid
Paint a region from a character grid + legend
Palette Management (5 tools)
Tool
Description
get_palette
Get all palette colors
set_palette_color
Set color at palette index
load_palette
Load palette from file
create_palette
Create palette from color list
resize_palette
Change number of palette entries
Selection Operations (4 tools)
Tool
Description
select_rect
Create rectangular selection
select_all
Select entire canvas
deselect
Clear selection
invert_selection
Invert current selection
Transform Operations (4 tools)
Tool
Description
flip_sprite
Flip horizontal/vertical
rotate_sprite
Rotate by 90/180/270 degrees
crop_sprite
Crop to rectangle or auto-crop to content
trim_sprite
Auto-trim transparent borders
Tag Operations (4 tools)
Tool
Description
create_tag
Create animation tag over frame range
remove_tag
Remove tag by name
list_tags
List all tags with frame ranges
set_tag_properties
Modify tag name, color, direction, repeat count
Export Operations (4 tools)
Tool
Description
export_png
Export sprite/frames as PNG
export_spritesheet
Generate sprite sheet with JSON metadata
export_gif
Export as animated GIF
render_sprite
Return an upscaled PNG as image content
Cel Operations (4 tools)
Tool
Description
clear_cel
Clear cel content
get_cel_info
Get cel position, opacity, bounds
copy_cel
Copy cel content between frames/layers
move_cel
Move/translate cel content by offset
Tileset & Tilemap (3 tools)
Tool
Description
create_tilemap_layer
Create a tilemap layer with tileset grid
set_tile
Place a tile at grid coordinates
get_tileset_info
Get tileset metadata and tile count
Batch Operations (3 tools)
Tool
Description
batch_export
Export frames/layers as individual PNGs
batch_resize
Resize multiple sprites by scale factor
import_spritesheet
Import spritesheet PNG and split into frames
Color & Analysis (4 tools)
Tool
Description
analyze_colors
Count unique colors, find most/least used
quantize_colors
Reduce color count to target palette size
generate_palette
Auto-generate palette from sprite colors
color_ramp
Generate color gradient between two colors
Tool Filtering
Filter which tools are exposed using environment variables:
# Only expose sprite and drawing tools
MCP_TOOLSETS=sprite,drawing
# Exclude specific tools
MCP_EXCLUDE_TOOLS=flood_fill,export_gif
# Read-only mode (only get_*, list_*, open_* tools)
MCP_READ_ONLY=true
Development
pnpm install # Install dependencies
pnpm build # Compile TypeScript + copy Lua scripts
pnpm test # Run all tests (requires Aseprite)
pnpm test:unit # Run unit tests only
pnpm lint # ESLint
pnpm format:check # Prettier check
pnpm typecheck # TypeScript check
pnpm inspector # Open MCP Inspector
pnpm watch # Auto-rebuild on changes
Troubleshooting
Aseprite not found
The server auto-detects Aseprite from common locations including Steam, /usr/bin, /usr/local/bin, /Applications, and standard Windows paths. If auto-detection fails, set the ASEPRITE_PATH environment variable:
# Linux
export ASEPRITE_PATH=/usr/bin/aseprite
# macOS
export ASEPRITE_PATH=/Applications/Aseprite.app/Contents/MacOS/aseprite
# Windows
set ASEPRITE_PATH=C:\Program Files\Aseprite\Aseprite.exe
Debug output
Set DEBUG=true to see detailed operation logs in stderr.
