Aseprite

You run the Aseprite MCP Server to interact with Aseprite programmatically, enabling scripted drawing, palette management, batch processing, and data exchange through a live service. This server exposes a set of drawing, palette, export, and batch tools that you can drive from your MCP client, making repetitive tasks reliable and automatable.

How to use

Your MCP client communicates with the Aseprite MCP Server to perform canvas operations, manage layers and frames, apply palettes, export assets, and run batch tasks. You can execute individual commands to create sprites, draw pixels or shapes, apply palettes, and export results. For batch workflows, you can resize many sprites, export in bulk, or apply a common palette across a folder of files. The server provides structured error handling and logging to help you troubleshoot problems quickly.

Key capabilities you can leverage include creating a new sprite canvas, drawing primitives, managing layers and frames, working with predefined and custom palettes, exporting to PNG or GIF, and performing batch operations across multiple files. You can also generate clean, type-safe Lua scripts for advanced automations and execute them on sets of sprites.

How to install

Prerequisites you need before starting are Python 3.13 or later and Aseprite installed on your system. You will run the MCP server locally and connect to it from your MCP client, either using a local stdio startup or via a dedicated command-line runner.

Step-by-step setup

1. Install Python dependencies

pip install -r requirements.txt

2. Prepare the MCP server startup configuration

Choose one of the runtime options shown below. Each option runs the MCP server locally on your machine and exposes the drawing and batch tools to your MCP client.

Configuration

Environment variables control where Aseprite is located and how the MCP server logs. You should define ASEPRITE_PATH to point to your Aseprite executable. You can also set ASEPRITE_MCP_LOG_LEVEL to adjust logging verbosity.

{
  "aseprite_path": "/path/to/aseprite",
  "canvas": {
    "max_width": 10000,
    "max_height": 10000
  },
  "batch": {
    "max_parallel_jobs": 4,
    "continue_on_error": true
  },
  "log_level": "INFO",
  "security": {
    "allowed_directories": ["/home/user/sprites"],
    "max_file_size": 104857600
  }
}

Environment variables example

export ASEPRITE_PATH="/Applications/Aseprite.app/Contents/MacOS/aseprite"
export ASEPRITE_MCP_LOG_LEVEL="INFO"

Usage examples

The MCP server exposes a rich set of operations for drawing, layering, palette handling, exporting, and batch processing. Use your MCP client to invoke these operations and build complex automation pipelines that fit your workflow.

Available tools

create_canvas

Create a new sprite canvas with layers and frames as needed.

draw_pixels

Set individual pixel colors on the canvas.

draw_rectangle

Draw a filled or hollow rectangle with a specified color.

draw_circle

Draw a circle with a given center, radius, and color.

draw_line

Draw a straight line between two points with a given color and thickness.

fill_area

Fill a contiguous region starting from a point with a color.

add_layer

Add a new layer to the sprite.

add_frame

Add an animation frame, optionally after a specified frame.

apply_preset_palette

Apply one of several preset palettes to a sprite.

create_palette

Create a custom palette from a list of colors.

extract_palette_from_image

Extract a color palette from a reference image.

get_palette_info

Retrieve details about the active or a specified palette.

remap_colors

Remap colors across the entire sprite set according to a mapping.

export_sprite

Export a single sprite to a target image or animation format.

batch_resize

Resize multiple sprites in parallel while preserving aspect ratio.

batch_export

Export a batch of sprites to a chosen format and scale.

batch_apply_palette

Apply a palette to multiple files in a batch.

batch_process_custom

Run a Lua script across a set of files as a batch operation.

Lua Script Builder

Generate clean, type-safe Lua scripts for automations.