create_canvasLABSCO SUMMARY
Batch operations are where this stops being a novelty.
Drawing a rectangle by conversation is a demo. Resizing every sprite in a directory to half scale, or applying one palette across a folder with backups, is the work that would otherwise be an afternoon of clicking. The security settings deserve a look before you point it at anything: allowed_directories and a maximum file size are configurable, and they bound what generated Lua can touch.
What it is
A Python MCP server that generates Lua for Aseprite and runs it against your local installation. It covers drawing, palettes, export and bulk operations, with input validation and path-traversal protection between the model and your filesystem.
What you get
- create_canvas makes a sprite; add_layer and add_frame build up layers and animation frames
- draw_pixels, draw_line, draw_rectangle, draw_circle and fill_area cover drawing, with hex colours, fill and thickness options and a tolerance on the fill
- apply_preset_palette applies gameboy, gameboy-pocket, nes, pico-8, cga, monochrome or sepia; create_palette takes your own hex list
- extract_palette_from_image pulls colours out of a reference image, get_palette_info reports what a sprite uses, and remap_colors swaps one colour for another throughout
- export_sprite writes out with a scale and an optional frame range; export_layers writes each layer separately
- batch_resize, batch_export and batch_apply_palette process a directory with a file pattern, and batch_process_custom runs your own Lua across a file set
- Configuration through JSON or YAML sets canvas limits, parallel batch jobs, allowed directories and a maximum file size
Requirements
Python 3.13 or newer and a separately installed copy of Aseprite. ASEPRITE_PATH must point at the executable — for example /Applications/Aseprite.app/Contents/MacOS/aseprite on macOS. Run with uv or as python -m aseprite_mcp from a checkout; ASEPRITE_MCP_LOG_LEVEL controls logging.
Setup effort
Build from source — get the source, then follow the project's own run instructions
USE CASES
01
Starting a sprite from a description
Create the canvas, add layers, and draw the shapes without opening the editor.
02
Giving artwork a consistent retro palette
Preset palettes by name, or a custom list of hex colours applied across the sprite.
03
Matching an existing piece's colours
Extract the palette from a reference image, then remap the sprite onto it.
04
Preparing a folder of assets for release
Resize and export a whole directory in one pass, with the file pattern you choose.
05
Running your own Aseprite script over many files
Custom Lua applied across a file set with a separate output directory.
19 tools
Listed in project docs. Your client may show a different list.
add_layeradd_framedraw_pixelsdraw_rectangledraw_circledraw_linefill_areaapply_preset_palettecreate_paletteextract_palette_from_imageget_palette_inforemap_colorsexport_spriteexport_layersbatch_resizebatch_exportbatch_apply_palettebatch_process_customBEFORE YOU INSTALL
What to know first
Tools you get
19 tools named in the project's documentation.
Requires
- python on PATH
- Python 3.13+
Where it runs
Both documented setups run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
python -m aseprite_mcpMCP Clients
Claude Desktop — uv
CLAUDE DESKTOP — UV · JSON
{
"mcpServers": {
"aseprite": {
"command": "/opt/homebrew/bin/uv",
"args": [
"--directory",
"<YOUR_PATH_TO_ASEPRITE_MCP>",
"run",
"-m",
"aseprite_mcp"
],
"env": {
"ASEPRITE_PATH": "<YOUR_ASEPRITE_PATH>"
}
}
}
}Claude Desktop — Python
CLAUDE DESKTOP — PYTHON · JSON
{
"mcpServers": {
"aseprite": {
"command": "python",
"args": [
"-m",
"aseprite_mcp"
],
"cwd": "<YOUR_PATH_TO_ASEPRITE_MCP>",
"env": {
"ASEPRITE_PATH": "<YOUR_ASEPRITE_PATH>"
}
}
}
}
