Skip to main content
Glama
Aseprite MCP Tools

Aseprite MCP Tools

by ZeroTian

Aseprite MCP Tools

A Python MCP server that gives AI assistants full control over Aseprite for creating pixel art and animated sprites.

104 tools across 17 categories — canvas, drawing, layers, animation, palettes, effects, slices, tilemaps, exports, visual-feedback/analysis tools, and a raw Lua escape hatch. The tool set is designed so an LLM has everything it needs to produce good pixel art, not just primitives: shading ramps with hue shifting, ordered dithering, outlines, retro palette presets with quantization, onion-skin renders, and frame diffing for animation work.

Example: a swordsman, drawn and animated by Claude

Both were created end-to-end by Claude Fable 5 through this server's MCP tools — drawing, checking its own work with scaled export_frame previews and render_onion_skin, then exporting. The tasks recreate the benchmark from Draw Me a Swordsman by Lj Miranda, whose findings inspired this server's expanded toolset.

Related MCP server: mnehmos.aseprite.mcp

Tool Categories

Category

Tools

Description

Canvas

6

Create sprites, manage layers/frames, set the active state

Drawing

14

Pixels, lines, rectangles, circles, ellipses, polygons, paths, fills, gradients

Layers

7

Delete, rename, duplicate, reorder, blend modes, merge, flatten

Selection & Regions

4

Move, copy, and erase rectangular regions or colors

Effects

5

Outlines, color replacement, HSL adjustment, ordered dithering

Animation

24

Frames, cels, tags, tweening with easing, propagation

Palette

8

Get/set palettes, retro presets, color ramps, quantization, color modes

Transform

4

Flip, rotate, resize, crop

Slices

5

Named regions, 9-patch centers, pivot points

Tilemap

5

Tilemap layers, tileset editing, tile placement

Export & Import

7

PNG, GIF, sprite sheets, per-layer/per-tag export, image import

Inspection

3

Read pixels and sprite metadata

Analysis & Visual Feedback

3

Onion-skin renders, frame diffing, color statistics

Quality

4

Validate and sanitize animation consistency

Scene

1

Copy layers between sprite files

Preview & Guide

3

Local HTTP preview server, workflow guide

Scripting

1

Raw Lua escape hatch for anything not covered above

Canvas

Tool

Description

create_canvas

Create a new sprite with the given dimensions

add_layer

Add a new layer, optionally inside a named group

add_group

Add a new (optionally nested) group layer

add_frame

Append a new frame

set_frame

Set the active frame

set_frame_duration

Set one frame's duration in ms

set_layer

Set the active layer (optionally creating it)

Drawing

All _at variants target a specific layer/frame and can create the cel on demand. Coordinates are sprite-global.

Tool

Description

draw_pixels

Plot individual pixels with per-pixel colors

draw_pixels_at

Plot pixels on a specific layer/frame

draw_line / draw_line_at

Lines with thickness

draw_rectangle / draw_rectangle_at

Outlined or filled rectangles

draw_circle / draw_circle_at

Outlined or filled circles

draw_ellipse_at

Outlined or filled ellipses with separate x/y radii

draw_polygon

Outlined or filled polygons from a point list

draw_path

Polyline through a point list with thickness

fill_area / fill_area_at

Paint-bucket flood fill

apply_gradient_rect

Smooth linear gradient fill in a rectangle

Layers

Tool

Description

delete_layer

Delete a layer by name

rename_layer

Rename a layer

duplicate_layer

Duplicate a layer with all cels, opacity, and blend mode, optionally into a group

reorder_layer

Move a layer to a position in the stack

set_layer_blend_mode

Set blend mode (multiply, screen, overlay, ... 19 modes)

merge_layer_down

Merge a layer into the one below it

flatten_sprite

Flatten all layers into one

Selection & Regions

Tool

Description

move_region

Cut a rectangle of pixels and paste it elsewhere

copy_region

Copy a rectangle to another position, layer, or frame

erase_region

Make a rectangle transparent

erase_color

Magic-eraser: make all pixels of a color transparent (with tolerance)

Effects

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

Tool

Description

outline_cel

Add a 1px outline around all opaque pixels

replace_color

Replace one color with another (with tolerance), preserving alpha

adjust_hsl

Shift hue/saturation/lightness of a cel — palette swaps, night scenes, shadows

apply_dither_gradient

Two-color gradient using Bayer 4×4 ordered dithering

apply_dither_pattern

Uniform dithered mix of two colors at a given density

Animation

Tool

Description

add_frames

Append N frames with optional duration

delete_frame

Delete a frame

set_frame_duration_all

Set every frame's duration

duplicate_frame_range

Duplicate a frame range N times

copy_frame / propagate_frame_to_range

Copy all cels of a frame to other frames

create_cel / clear_cel / copy_cel

Cel lifecycle on a layer/frame

propagate_cels

Copy selected layers' cels across a frame range

set_cel_position

Place a cel at x,y

set_cel_opacity

Set a single cel's opacity

offset_cel_positions

Shift cels by a delta across frames

tween_cel_positions

Linear position tween across frames

tween_cel_positions_eased

Position tween with easing (ease_in/out, smoothstep)

tween_cel_opacity_eased

Opacity tween with easing

tween_cel_scale_eased

Scale tween with easing and anchor

oscillate_cel_positions

Sine-wave motion (bobbing, breathing, hovering)

set_tag / delete_tag

Animation tags with direction (forward/reverse/pingpong)

set_layer_visibility / set_layer_opacity

Layer-level visibility and opacity

set_onion_skin

Configure onion-skin UI prefs (see render_onion_skin for batch use)

get_sprite_info

Sprite metadata: size, layers, frames, durations, tags

Palette

Tool

Description

get_palette

Read the palette as hex colors

set_palette

Set the palette from a list of hex colors

list_palette_presets

List built-in retro palettes

apply_palette_preset

Apply a preset: gameboy, pico8, c64, cga, dawnbringer16, dawnbringer32, grayscale_4, monochrome

generate_color_ramp

Build a dark→light shading ramp with hue shifting from a base color

quantize_to_palette

Snap every pixel to the nearest palette color

remap_colors_in_cel_range

Remap specific colors across a frame range

set_color_mode

Convert between RGB, grayscale, and indexed

Transform

Tool

Description

flip_layer

Flip a cel horizontally or vertically

rotate_layer

Rotate a cel 90/180/270°

resize_canvas

Scale the sprite to new dimensions

crop_canvas

Crop to a rectangle

Slices

Tool

Description

create_slice

Create a named rectangular region

set_slice_center

Set the 9-patch stretchable center

set_slice_pivot

Set the pivot point

list_slices

List all slices with bounds, centers, pivots as JSON

delete_slice

Delete a slice

Tilemap

Tool

Description

create_tilemap_layer

Add a tilemap layer with its own tileset and tile grid

draw_on_tile

Paint pixels into a tileset tile (auto-appends new tiles)

set_tiles

Place tiles on the map by grid position

get_tile_at

Read which tile occupies a grid cell

get_tilemap_info

Tile size, tile count, and map dimensions as JSON

Export & Import

Tool

Description

export_sprite

Export to PNG, GIF, JPG, ...

export_frame

Export one frame as PNG with integer upscaling — the core visual-feedback loop: draw, export at 8×, look, iterate

export_spritesheet

Sprite sheet (horizontal/vertical/rows/columns/packed) with optional JSON metadata and per-tag filtering

export_layers

One PNG per layer

export_tag

Export an animation tag as GIF or PNG sequence

import_image_as_layer

Import a PNG into a layer (references, premade parts)

copy_sprite

Duplicate the .aseprite file

Inspection

Tool

Description

get_pixel_color

Read one pixel's RGBA

get_pixels_rect

Read a rectangle of pixels as JSON

get_sprite_info

Sprite metadata (also listed under Animation)

Analysis & Visual Feedback

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

Tool

Description

render_onion_skin

Render a frame over translucent ghosts of neighboring frames — check motion continuity without opening Aseprite

compare_frames

Diff two frames: changed pixel count, percentage, bounding box

get_color_stats

Color histogram of a frame — catches palette drift and near-duplicate colors

Quality

Tool

Description

ensure_layers_present

Create missing cels for layers across a frame range

validate_scene

Report missing layers/cels as JSON

audit_animation

Audit frames for overlaps and out-of-range layer activity

animation_sanitize

Normalize layer order, coverage, and overlaps

Scene

Tool

Description

copy_layers_between_sprites

Copy layers by name from one .aseprite file to another

Preview & Guide

Tool

Description

start_preview_server / stop_preview_server

Serve exported files over local HTTP

animation_workflow_guide

Returns a step-by-step workflow guide for the LLM

Scripting

Tool

Description

run_lua_script

Execute arbitrary Aseprite Lua (API docs) in batch mode. The escape hatch when no dedicated tool fits: one script can batch many operations into a single Aseprite launch. Remember to spr:saveAs(spr.filename) and print() your results. ⚠️ Runs unrestricted code on the host — only pass scripts you trust.

  1. Plan the palette first: generate_color_ramp for each material (skin, armor, blade), or apply_palette_preset for a retro look.

  2. Build in layers: background / body / equipment / effects, so parts can be animated and edited independently.

  3. Draw coarse to fine: silhouette with draw_rectangle_at / draw_ellipse_at / fill_area_at, then refine with draw_pixels_at.

  4. Look at your work: export_frame at 8×, inspect, fix, repeat. Use get_color_stats to keep the palette tight.

  5. Shade with intent: adjust_hsl for shadow layers, apply_dither_gradient for blends, outline_cel for readability.

  6. Animate with the cel tools: propagate_cels, then tween_cel_positions_eased / oscillate_cel_positions; verify with render_onion_skin and compare_frames; export with export_tag.

Docker Usage

Quick Start

Build and run the Docker image:

docker build -t aseprite-mcp:latest .
docker run -it --rm aseprite-mcp:latest

Or use the provided build scripts:

  • Linux/macOS: chmod +x build-docker.sh && ./build-docker.sh

  • Windows: .\build-docker.ps1

Using Docker Compose

# Production
docker-compose up aseprite-mcp

# Development mode
docker-compose --profile dev up aseprite-mcp-dev

See DOCKER.md for detailed Docker setup instructions.

Optional: Install Aseprite via Steam

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

# Create a .env with STEAM_USERNAME/STEAM_PASSWORD (and optional STEAM_GUARD_CODE)
# Then
docker run --rm -i --env-file .env aseprite-mcp:latest

If installed, the binary will be at /opt/steamapps/common/Aseprite/aseprite and ASEPRITE_PATH will be picked up automatically.

Local Installation

Prerequisites

  • Python 3.13+

  • uv package manager

  • Aseprite (set ASEPRITE_PATH in .env if it is not on your PATH)

Installation:

{
  "mcpServers": {
      "aseprite": {
          "command": "/opt/homebrew/bin/uv",
          "args": [
              "--directory",
              "/path/to/repo",
              "run",
              "-m",
              "aseprite_mcp"
          ]
      }
  }
}

Available Tools

113 tools
add_frameC

Add a new frame to the Aseprite file.

Args: filename: Name of the Aseprite file to modify

Inputs: filename (required).

add_framesA

Add multiple frames to a sprite and optionally set their duration.

Args: filename: Name of the Aseprite file to modify count: Number of frames to add duration_ms: Optional duration for each new frame in milliseconds

Inputs: filename (required), count (required), duration_ms.

add_groupA

Add a new, empty group layer.

Combine with add_layer(group=...) / duplicate_layer(group=...) to build a grouped layer structure.

Args: filename: Name of the Aseprite file to modify group_name: Name of the new group parent_group: Optional existing group to nest the new group inside, by name or "group/subgroup" path (default: top level)

Inputs: filename (required), group_name (required), parent_group.

add_layerA

Add a new layer to the Aseprite file.

Args: filename: Name of the Aseprite file to modify layer_name: Name of the new layer group: Optional group to place the new layer inside, by name or "group/subgroup" path (default: top level)

Inputs: filename (required), layer_name (required), group.

adjust_brightness_contrastB

Native Brightness/Contrast filter (app.command.BrightnessContrast).

Args: filename: Aseprite file to modify layer_name: layer to adjust (empty = active layer) frame_index: 1-based frame brightness: -100..100 contrast: -100..100 x, y, width, height: optional region (width>0 & height>0 to scope)

Inputs: filename (required), layer_name, frame_index, brightness, +5 more.

adjust_hslA

Shift hue, saturation, and lightness of all opaque pixels in a cel.

Useful for creating palette-swapped variants and shading: e.g. darken a duplicated layer for shadows or hue-shift toward blue for night scenes.

Args: filename: Aseprite file to modify layer_name: Layer to adjust frame_index: Frame index starting at 1 hue_shift: Degrees to rotate hue, -360 to 360 saturation_shift: Saturation delta, -100 to 100 lightness_shift: Lightness delta, -100 to 100

Inputs: filename (required), layer_name (required), frame_index (required), hue_shift, +2 more.

adjust_hsl_nativeA

Native Hue/Saturation/Lightness filter (engine-quality vs adjust_hsl).

Args: filename: Aseprite file to modify layer_name: layer to adjust (empty = active layer) frame_index: 1-based frame hue: -180..180 (degrees) saturation: -100..100 lightness: -100..100 x, y, width, height: optional region (width>0 & height>0 to scope)

Inputs: filename (required), layer_name, frame_index, hue, +6 more.

animation_sanitizeC

Normalize animation consistency and optionally apply fixes.

layer_frame_ranges format: ["layer:1-8,17-24", "clouds:1-12"] out_of_range_action: "set_opacity_zero", "delete_cels", "none" ignore_full_canvas_overlaps: skip overlap checks when a cel is full canvas Returns JSON for AI consumption (summary, layer_stats, alerts, overlaps).

Inputs: filename (required), start_frame, end_frame, layer_names, +11 more.

animation_workflow_guideB

Return a concise English guide for optimized animation workflows.

Inputs: use_case.

apply_convolutionA

Native convolution filter (blur / sharpen / edge / emboss …).

Args: filename: Aseprite file to modify matrix: a built-in matrix name (see list_convolution_matrices), e.g. "blur-3x3", "sharpen-3x3", "edges-find", "misc-emboss" layer_name: layer to filter (empty = active layer) frame_index: 1-based frame x, y, width, height: optional region (width>0 & height>0 to scope)

Inputs: filename (required), matrix (required), layer_name, frame_index, +4 more.

apply_dither_gradientA

Fill a rectangle with a two-color gradient using Bayer 4x4 ordered dithering.

This is the classic pixel-art way to blend two colors without introducing new intermediate colors. The gradient runs from color_start (top/left) to color_end (bottom/right).

Args: filename: Aseprite file to modify layer_name: Layer to draw on frame_index: Frame index starting at 1 x: Left edge of the rectangle y: Top edge of the rectangle width: Rectangle width height: Rectangle height color_start: Hex color at the start of the gradient color_end: Hex color at the end of the gradient horizontal: Run the gradient left-to-right instead of top-to-bottom create_if_missing: Create the cel if it does not exist

Inputs: filename (required), layer_name (required), frame_index (required), x (required), +7 more.

apply_dither_patternB

Fill a rectangle with a uniform Bayer-dithered mix of two colors.

density controls the ratio: 0.0 = all color_a, 0.5 = checkerboard, 1.0 = all color_b. Useful for textures (stone, grass) and flat mid-tones between two palette colors.

Args: filename: Aseprite file to modify layer_name: Layer to draw on frame_index: Frame index starting at 1 x: Left edge of the rectangle y: Top edge of the rectangle width: Rectangle width height: Rectangle height color_a: Base hex color color_b: Mixed-in hex color density: Fraction of color_b, 0.0-1.0 (default 0.5) create_if_missing: Create the cel if it does not exist

Inputs: filename (required), layer_name (required), frame_index (required), x (required), +7 more.

apply_gradient_rectC

Apply a linear gradient fill to a rectangle.

Inputs: filename (required), layer_name (required), frame_index (required), x (required), +7 more.

apply_palette_presetA

Set the sprite palette to a built-in retro preset.

This only sets the palette; existing pixels keep their colors. Use quantize_to_palette afterwards to snap pixels to the new palette.

Args: filename: Aseprite file to modify preset: One of: gameboy, monochrome, grayscale_4, cga, pico8, c64, dawnbringer16, dawnbringer32

Inputs: filename (required), preset (required).

audit_animationB

Audit animation frames for overlaps and out-of-range layer activity.

overlap_pairs format: ["layerA,layerB", "layerC:layerD"] layer_frame_ranges format: ["layer:1-8,17-24", "clouds:1-12"] Returns JSON for AI consumption (summary, overlaps, out_of_range, optional cels).

Inputs: filename (required), start_frame, end_frame, layer_names, +6 more.

clear_celC

Delete a cel on a layer/frame.

Inputs: filename (required), layer_name (required), frame_index (required).

compare_framesA

Compare two frames and report how much they differ.

Flattens the sprite (non-destructively) and diffs the two frames pixel by pixel. Use while animating to confirm a frame actually changed, or that it did not change too much.

Args: filename: Aseprite file to read frame_a: First frame index, starting at 1 frame_b: Second frame index, starting at 1

Returns: JSON with changed pixel count, total pixels, percent changed, and the bounding box of the changed region.

Inputs: filename (required), frame_a (required), frame_b (required).

copy_celC

Copy a cel from one frame to another.

Inputs: filename (required), layer_name (required), source_frame (required), target_frame (required), +1 more.

copy_frameC

Copy all cels from a source frame to a target frame (or append).

Inputs: filename (required), source_frame (required), target_frame, overwrite.

copy_layers_between_spritesB

Copy layers by name from a source sprite to a target sprite.

Args: source_filename: Source .aseprite file target_filename: Target .aseprite file layer_names: List of layer names to copy replace: Overwrite existing cels in target layers create_missing_frames: Add frames to target if needed

Inputs: source_filename (required), target_filename (required), layer_names (required), replace, +1 more.

copy_regionA

Copy a rectangular region of pixels to another position, layer, or frame.

Coordinates are sprite-global. Fully transparent source pixels do not overwrite destination pixels. The destination cel is created when missing.

Args: filename: Aseprite file to modify layer_name: Source layer frame_index: Source frame index starting at 1 x: Left edge of the source region y: Top edge of the source region width: Region width height: Region height dest_x: Left edge of the destination dest_y: Top edge of the destination target_layer_name: Destination layer (default: same as source) target_frame_index: Destination frame (default: same as source)

Inputs: filename (required), layer_name (required), frame_index (required), x (required), +7 more.

copy_spriteC

Copy a sprite to a new Aseprite file.

Args: filename: Name of the Aseprite file to copy output_filename: Name of the output .aseprite file overwrite: Whether to overwrite if output exists

Inputs: filename (required), output_filename (required), overwrite.

create_canvasA

Create a new Aseprite canvas with specified dimensions.

Args: width: Width of the canvas in pixels height: Height of the canvas in pixels filename: Name of the output file (default: canvas.aseprite)

Inputs: width (required), height (required), filename.

create_celC

Create an empty cel on a layer/frame.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target frame_index: Frame index starting at 1 x: X position in pixels y: Y position in pixels

Inputs: filename (required), layer_name (required), frame_index (required), x, +1 more.

create_sliceB

Create a named slice (a rectangular region usable by game engines).

Args: filename: Aseprite file to modify name: Slice name x: Left edge of the slice y: Top edge of the slice width: Slice width height: Slice height

Inputs: filename (required), name (required), x (required), y (required), +2 more.

create_tilemap_layerA

Create a tilemap layer with its own tileset.

Sets the sprite grid to the tile size and adds a tilemap layer. Tile index 0 is always the empty tile; add real tiles with draw_on_tile (which creates tiles on demand).

Args: filename: Aseprite file to modify layer_name: Name for the new tilemap layer tile_width: Tile width in pixels tile_height: Tile height in pixels

Inputs: filename (required), layer_name (required), tile_width (required), tile_height (required).

crop_canvasA

Crop the canvas to the given rectangle, discarding content outside it.

Args: filename: Aseprite file to modify x: Left edge of the crop area y: Top edge of the crop area width: Width of the crop area height: Height of the crop area

Inputs: filename (required), x (required), y (required), width (required), +1 more.

delete_frameB

Delete a frame by index.

Args: filename: Aseprite file to modify frame_index: Frame index starting at 1

Inputs: filename (required), frame_index (required).

delete_layerC

Delete a layer by name.

Args: filename: Aseprite file to modify layer_name: Name of the layer to delete

Inputs: filename (required), layer_name (required).

delete_sliceB

Delete a slice by name.

Args: filename: Aseprite file to modify name: Slice name to delete

Inputs: filename (required), name (required).

delete_tagA

Delete an animation tag by name.

Args: filename: Aseprite file to modify name: Tag name to delete

Inputs: filename (required), name (required).

draw_circleB

Draw a circle on the canvas.

Args: filename: Name of the Aseprite file to modify center_x: X coordinate of circle center center_y: Y coordinate of circle center radius: Radius of the circle in pixels color: Hex color code (default: "#000000") fill: Whether to fill the circle (default: False)

Inputs: filename (required), center_x (required), center_y (required), radius (required), +2 more.

draw_circle_atC

Draw a circle on a specific layer/frame.

Inputs: filename (required), layer_name (required), frame_index (required), center_x (required), +5 more.

draw_ellipse_atA

Draw an ellipse on a specific layer/frame.

Args: filename: Aseprite file to modify layer_name: Layer to draw on frame_index: Frame index starting at 1 center_x: Ellipse center x center_y: Ellipse center y radius_x: Horizontal radius in pixels radius_y: Vertical radius in pixels color: Hex color code (default "#000000") fill: Fill the ellipse instead of outlining it create_if_missing: Create the cel if it does not exist

Inputs: filename (required), layer_name (required), frame_index (required), center_x (required), +6 more.

draw_lineB

Draw a line on the canvas.

Args: filename: Name of the Aseprite file to modify x1: Starting x coordinate y1: Starting y coordinate x2: Ending x coordinate y2: Ending y coordinate color: Hex color code (default: "#000000") thickness: Line thickness in pixels (default: 1)

Inputs: filename (required), x1 (required), y1 (required), x2 (required), +3 more.

draw_line_atB

Draw a line on a specific layer/frame.

Inputs: filename (required), layer_name (required), frame_index (required), x1 (required), +6 more.

draw_on_tileA

Draw pixels onto a tile in a tilemap layer's tileset.

Coordinates are tile-local (0,0 = tile top-left). When tile_index equals the current tile count, a new tile is appended automatically.

Args: filename: Aseprite file to modify layer_name: Tilemap layer whose tileset to edit tile_index: Tile to draw on (1 = first real tile; 0 is reserved for the empty tile and cannot be drawn on) pixels: List of {"x": int, "y": int, "color": "#RRGGBB"}

Inputs: filename (required), layer_name (required), tile_index (required), pixels (required).

draw_pathC

Draw a path using a polyline on a specific layer/frame.

Inputs: filename (required), layer_name (required), frame_index (required), points (required), +3 more.

draw_pixelsA

Draw pixels on the canvas with specified colors.

Args: filename: Name of the Aseprite file to modify pixels: List of pixel data, each containing: {"x": int, "y": int, "color": str} where color is a hex code like "#FF0000"

Inputs: filename (required), pixels (required).

draw_pixels_atC

Draw pixels on a specific layer/frame.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target frame_index: Frame index starting at 1 pixels: List of pixel data with x/y/color create_if_missing: Create cel if it does not exist

Inputs: filename (required), layer_name (required), frame_index (required), pixels (required), +1 more.

draw_polygonC

Draw a polygon on a specific layer/frame.

Inputs: filename (required), layer_name (required), frame_index (required), points (required), +3 more.

draw_rectangleB

Draw a rectangle on the canvas.

Args: filename: Name of the Aseprite file to modify x: Top-left x coordinate y: Top-left y coordinate width: Width of the rectangle in pixels (must be > 0) height: Height of the rectangle in pixels (must be > 0) color: Hex color code (default: "#000000") fill: Whether to fill the rectangle (default: False)

Inputs: filename (required), x (required), y (required), width (required), +3 more.

draw_rectangle_atC

Draw a rectangle on a specific layer/frame.

Inputs: filename (required), layer_name (required), frame_index (required), x (required), +6 more.

duplicate_frame_rangeA

Duplicate a frame range and append copies to the end.

Args: filename: Name of the Aseprite file to modify start_frame: Starting frame index (1-based) end_frame: Ending frame index (1-based, inclusive) times: Number of times to append the range (default: 1)

Inputs: filename (required), start_frame (required), end_frame (required), times.

duplicate_layerA

Duplicate a layer with all its cels across every frame.

The copy inherits the source's opacity and blend mode. By default it is placed directly above the source layer; pass group to place it inside a group instead.

Args: filename: Aseprite file to modify layer_name: Layer to duplicate, by name or "group/subgroup/layer" path new_name: Name for the copy (default: "<layer_name> copy") group: Optional group to place the copy inside, by name or "group/subgroup" path (default: directly above the source)

Inputs: filename (required), layer_name (required), new_name, group.

ensure_layers_presentC

Ensure cels exist for layers across a frame range.

Inputs: filename (required), layer_names (required), start_frame, end_frame.

erase_colorA

Make all pixels of a given color transparent (like a magic eraser).

Args: filename: Aseprite file to modify layer_name: Layer to operate on frame_index: Frame index starting at 1 color: Hex color to erase, e.g. "#FF00FF" tolerance: Per-channel tolerance 0-255 (default 0 = exact match)

Inputs: filename (required), layer_name (required), frame_index (required), color (required), +1 more.

erase_regionA

Erase (make transparent) a rectangular region of pixels.

Coordinates are sprite-global.

Args: filename: Aseprite file to modify layer_name: Layer to operate on frame_index: Frame index starting at 1 x: Left edge of the region y: Top edge of the region width: Region width height: Region height

Inputs: filename (required), layer_name (required), frame_index (required), x (required), +3 more.

export_frameA

Export a single frame as a PNG, optionally scaled up.

Use this for visual feedback while drawing: export at scale 8-10 and open the PNG to inspect the result, then keep iterating.

Args: filename: Aseprite file to export frame_index: Frame index starting at 1 output_filename: Output PNG path scale: Integer nearest-neighbor scale factor (default 1)

Inputs: filename (required), frame_index (required), output_filename (required), scale.

export_layersA

Export each layer as its own PNG file named .png.

Args: filename: Aseprite file to export output_directory: Directory for the per-layer PNGs (created if missing) include_hidden: Also export hidden layers (default False)

Inputs: filename (required), output_directory (required), include_hidden.

export_spriteA

Export the Aseprite file to another format.

Args: filename: Name of the Aseprite file to export output_filename: Name of the output file format: Output format (default: "png", can be "png", "gif", "jpg", etc.)

Inputs: filename (required), output_filename (required), format.

export_spritesheetB

Export frames as a sprite sheet, optionally with a JSON data file.

Args: filename: Aseprite file to export output_filename: Output sheet image path (PNG) sheet_type: Layout: "horizontal", "vertical", "rows", "columns", or "packed" data_filename: Optional path for a JSON metadata file (json-array format) scale: Integer scale factor applied before packing (default 1) padding: Padding in pixels between frames (default 0) tag_name: Only include frames of this animation tag (default: all frames)

Inputs: filename (required), output_filename (required), sheet_type, data_filename, +3 more.

export_tagA

Export the frames of an animation tag as a GIF or PNG sequence.

Args: filename: Aseprite file to export tag_name: Animation tag to export output_filename: Output path; .gif gives an animation, .png a sequence scale: Integer scale factor (default 1)

Inputs: filename (required), tag_name (required), output_filename (required), scale.

extract_paletteA

Build an OPTIMAL palette from the sprite via native ColorQuantization.

True palette extraction (vs the nearest-snap quantize_to_palette): writes the resulting palette to the sprite and returns it. NOTE: mutates the sprite's palette. Sprite must be in RGB mode.

Args: filename: Aseprite file to modify max_colors: palette size cap, 1..256 (fewer if the art has fewer) with_alpha: include alpha when quantizing

Returns: JSON {colors: [#RRGGBB, ...], count}

Inputs: filename (required), max_colors, with_alpha.

fill_areaB

Fill an area with color using the paint bucket tool.

Args: filename: Name of the Aseprite file to modify x: X coordinate to fill from y: Y coordinate to fill from color: Hex color code (default: "#000000")

Inputs: filename (required), x (required), y (required), color.

fill_area_atC

Fill an area on a specific layer/frame.

Inputs: filename (required), layer_name (required), frame_index (required), x (required), +3 more.

flatten_spriteB

Flatten all layers into a single layer.

Args: filename: Aseprite file to modify

Inputs: filename (required).

flip_layerB

Flip a layer's image horizontally or vertically.

Args: filename: Aseprite file to modify layer_name: Layer name to flip frame_index: Frame index starting at 1 direction: "horizontal" or "vertical"

Inputs: filename (required), layer_name (required), frame_index (required), direction.

generate_color_rampA

Generate a shading ramp (dark to light) from a base color.

Produces the standard pixel-art shading technique of hue-shifting: shadows lean cooler (hue shifted one way), highlights lean warmer. Use the returned colors for shading instead of plain darker/lighter versions of the same hue.

Args: base_color: Hex color the ramp is built around, e.g. "#D04648" steps: Number of colors in the ramp, 2-16 (default 5) hue_shift_degrees: Total hue rotation across the ramp (default 20) lightness_range: Total lightness span across the ramp, 0-1 (default 0.5)

Returns: JSON array of hex colors ordered darkest to lightest.

Inputs: base_color (required), steps, hue_shift_degrees, lightness_range.

get_color_statsA

Report the colors used in a frame and how often each appears.

Flattens the sprite (non-destructively) and histograms the frame. Use to check palette discipline: too many near-duplicate colors is a common pixel-art mistake.

Args: filename: Aseprite file to read frame_index: Frame to analyze, starting at 1 (default 1) top: How many of the most-used colors to list (default 16)

Returns: JSON with unique color count, opaque pixel count, and the top colors with usage counts.

Inputs: filename (required), frame_index, top.

get_composite_pixelA

Read the RGBA colour VISIBLE at a pixel (flattened composite of all layers).

Unlike get_pixel_color (which reads a single cel), this composites every visible layer — "what the player actually sees" — by flattening a throwaway clone. Essential for value/CVD QA on grouped/multi-layer scenes.

Args: filename: Aseprite file to read x: X coordinate (sprite-global) y: Y coordinate (sprite-global) frame_index: Frame index starting at 1

Inputs: filename (required), x (required), y (required), frame_index.

get_composite_rectA

Read VISIBLE RGBA over a rectangle (flattened composite of all layers).

The rectangular counterpart of get_composite_pixel — reads the composited pixels every visible layer produces, not a single cel.

Args: filename: Aseprite file to read x: Top-left x (sprite-global) y: Top-left y (sprite-global) width: Region width height: Region height frame_index: Frame index starting at 1

Returns: JSON array of {x, y, hex, r, g, b, a} objects

Inputs: filename (required), x (required), y (required), width (required), +2 more.

get_paletteC

Get the active sprite palette as a JSON array of hex colors.

Inputs: filename (required).

get_pixel_colorA

Read the RGBA color of a single pixel.

Args: filename: Aseprite file to read x: X coordinate y: Y coordinate layer_name: Layer to read from (uses active layer when empty) frame_index: Frame index starting at 1

Inputs: filename (required), x (required), y (required), layer_name, +1 more.

get_pixels_rectA

Read all pixel colors in a rectangular region.

Args: filename: Aseprite file to read x: Top-left x coordinate y: Top-left y coordinate width: Width of the region height: Height of the region layer_name: Layer to read from (uses active layer when empty) frame_index: Frame index starting at 1

Returns: JSON array of {x, y, hex, r, g, b, a} objects

Inputs: filename (required), x (required), y (required), width (required), +3 more.

get_sprite_infoA

Return sprite info as JSON string (size, color mode, frame durations, layers, tags).

Args: filename: Name of the Aseprite file to inspect

Inputs: filename (required).

get_tile_atA

Read which tile is placed at a grid position.

Args: filename: Aseprite file to read layer_name: Tilemap layer to read frame_index: Frame index starting at 1 col: Grid column (0-based) row: Grid row (0-based)

Returns: JSON with {col, row, tile_index} (0 = empty).

Inputs: filename (required), layer_name (required), frame_index (required), col (required), +1 more.

get_tilemap_infoA

Get tilemap layer info: tile size, tile count, and map dimensions.

Args: filename: Aseprite file to read layer_name: Tilemap layer to inspect

Returns: JSON with tile_width, tile_height, tile_count (real tiles, excluding the empty tile 0), map_cols, map_rows.

Inputs: filename (required), layer_name (required).

import_image_as_layerA

Import an image file (PNG, etc.) into a layer of the sprite.

Useful for bringing in reference images or composing pre-made parts. The layer is created if it does not exist. Works best when the sprite is in RGB color mode.

Args: filename: Aseprite file to modify image_path: Image file to import layer_name: Layer to place the image on frame_index: Frame index starting at 1 (default 1) x: X position for the image's top-left corner (default 0) y: Y position for the image's top-left corner (default 0)

Inputs: filename (required), image_path (required), layer_name (required), frame_index, +2 more.

invert_colorsB

Native colour inversion (app.command.InvertColor).

Args: filename: Aseprite file to modify layer_name: layer to invert (empty = active layer) frame_index: 1-based frame x, y, width, height: optional region (width>0 & height>0 to scope)

Inputs: filename (required), layer_name, frame_index, x, +3 more.

list_convolution_matricesA

List the built-in convolution-matrix names usable with apply_convolution.

Returns: JSON array of matrix resource names.

Inputs: no named parameters.

list_palette_presetsA

List the built-in retro palette presets with their colors.

Returns: JSON object mapping preset name to its list of hex colors.

Inputs: no named parameters.

list_slicesA

List all slices with their bounds, 9-patch centers, and pivots.

Returns: JSON array of {name, x, y, width, height, center?, pivot?}.

Inputs: filename (required).

merge_layer_downB

Merge a layer into the layer directly below it.

Args: filename: Aseprite file to modify layer_name: Layer to merge down (must not be the bottom layer)

Inputs: filename (required), layer_name (required).

move_regionA

Cut a rectangular region of pixels and paste it at a new position.

Coordinates are sprite-global. The source area is left transparent. Pixels moved outside the canvas are discarded. Fully transparent source pixels do not overwrite destination pixels.

Args: filename: Aseprite file to modify layer_name: Layer to operate on frame_index: Frame index starting at 1 x: Left edge of the source region y: Top edge of the source region width: Region width height: Region height dest_x: New left edge for the region dest_y: New top edge for the region

Inputs: filename (required), layer_name (required), frame_index (required), x (required), +5 more.

offset_cel_positionsA

Offset cel positions by a delta across a frame range.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target start_frame: Starting frame index (1-based) end_frame: Ending frame index (1-based, inclusive) dx: X delta in pixels dy: Y delta in pixels

Inputs: filename (required), layer_name (required), start_frame (required), end_frame (required), +2 more.

oscillate_cel_positionsC

Oscillate cel positions across a frame range using a sine wave.

Inputs: filename (required), layer_name (required), start_frame (required), end_frame (required), +6 more.

outline_celA

Add a 1px outline around all opaque pixels of a cel.

Transparent pixels adjacent to opaque pixels are filled with the outline color. Great for making sprites read clearly against any background.

Args: filename: Aseprite file to modify layer_name: Layer to outline frame_index: Frame index starting at 1 color: Outline hex color (default black) include_diagonals: Also outline diagonal neighbors for a thicker, rounded outline (default False)

Inputs: filename (required), layer_name (required), frame_index (required), color, +1 more.

outline_nativeA

Native Aseprite Outline around opaque pixels (app.command.Outline).

Higher quality than the 1px hand-rolled outline_cel: inside/outside placement + a circle/square brush. Works best on a full-canvas cel.

Args: filename: Aseprite file to modify layer_name: layer to outline (empty = active layer) frame_index: 1-based frame color: outline colour as #RRGGBB place: "outside" or "inside" matrix: "circle" or "square"

Inputs: filename (required), layer_name, frame_index, color, +2 more.

propagate_celsB

Copy cels from a source frame to a range of frames for specific layers.

Args: filename: Name of the Aseprite file to modify layer_names: List of layer names to copy source_frame: Frame index to copy from (1-based) start_frame: Start frame index (1-based) end_frame: End frame index (1-based, inclusive) replace: Whether to overwrite existing cels (default: True)

Inputs: filename (required), layer_names (required), source_frame (required), start_frame (required), +2 more.

propagate_frame_to_rangeA

Copy all layers from a source frame to a range of frames.

Args: filename: Name of the Aseprite file to modify source_frame: Frame index to copy from (1-based) start_frame: Start frame index (1-based) end_frame: End frame index (1-based, inclusive) overwrite: Whether to overwrite existing cels (default: True)

Inputs: filename (required), source_frame (required), start_frame (required), end_frame (required), +1 more.

quantize_to_paletteA

Snap every pixel to the nearest color in the sprite's palette.

Walks the chosen cels and replaces each opaque pixel with the closest palette color (RGB distance). Run after apply_palette_preset or set_palette to make existing art conform to the palette.

Args: filename: Aseprite file to modify layer_name: Layer to quantize (empty = all top-level layers) start_frame: First frame to process (default 1) end_frame: Last frame to process (default 0 = last frame)

Inputs: filename (required), layer_name, start_frame, end_frame.

remap_colors_in_cel_rangeC

Remap colors in a layer across a frame range using explicit mappings.

Inputs: filename (required), layer_name (required), start_frame (required), end_frame (required), +3 more.

rename_layerC

Rename a layer.

Args: filename: Aseprite file to modify layer_name: Current layer name new_name: New layer name

Inputs: filename (required), layer_name (required), new_name (required).

render_onion_skinA

Render a frame with neighboring frames as translucent onion-skin ghosts.

Produces a PNG of the given frame composited over ghosted copies of the surrounding frames — the batch-mode equivalent of Aseprite's onion skinning. Essential for checking motion continuity while animating: export it, open the PNG, and verify the in-between positions line up.

Args: filename: Aseprite file to read frame_index: Frame to render, starting at 1 output_filename: Output PNG path before: Number of previous frames to ghost (default 1) after: Number of following frames to ghost (default 1) scale: Integer nearest-neighbor scale factor (default 4) ghost_opacity: Opacity of ghost frames, 0-255 (default 100)

Inputs: filename (required), frame_index (required), output_filename (required), before, +3 more.

reorder_layerA

Move a layer to a new position in the layer stack.

Args: filename: Aseprite file to modify layer_name: Layer to move position: Target stack position, 1-based where 1 is the bottom layer

Inputs: filename (required), layer_name (required), position (required).

replace_colorA

Replace one color with another in a cel, preserving alpha.

Args: filename: Aseprite file to modify layer_name: Layer to operate on frame_index: Frame index starting at 1 from_color: Hex color to replace, e.g. "#FF0000" to_color: Replacement hex color tolerance: Per-channel tolerance 0-255 (default 0 = exact match)

Inputs: filename (required), layer_name (required), frame_index (required), from_color (required), +2 more.

resize_canvasA

Scale the canvas and all its content to new dimensions.

Args: filename: Aseprite file to modify width: New canvas width in pixels height: New canvas height in pixels

Inputs: filename (required), width (required), height (required).

rotate_layerA

Rotate a layer's image 90, 180, or 270 degrees clockwise.

Args: filename: Aseprite file to modify layer_name: Layer name to rotate frame_index: Frame index starting at 1 angle: Rotation angle: 90, 180, or 270 (clockwise)

Inputs: filename (required), layer_name (required), frame_index (required), angle.

run_lua_scriptA

Execute arbitrary Aseprite Lua code in batch mode (escape hatch).

Use this when no dedicated tool covers what you need. The full API is documented at https://www.aseprite.org/api/. Anything the curated tools do can also be done here — they are Lua underneath.

Essentials for batch-mode scripts:

  • When filename is given, it is opened first and available as app.activeSprite.

  • Changes are NOT saved automatically; call spr:saveAs(spr.filename) at the end if you modified the sprite.

  • print() is the only way to return data; a clean exit does not mean your logic succeeded, so print what you need to verify.

  • Coordinates on cel images are cel-local: offset sprite-global coordinates by cel.position before getPixel/putPixel.

WARNING: this executes unrestricted code (including io/os access) on the host running Aseprite. Only pass scripts you trust.

Args: script: Lua source code to execute filename: Optional Aseprite file to open before running

Inputs: script (required), filename.

set_cel_opacityB

Set the opacity of a single cel (0-255).

Args: filename: Aseprite file to modify layer_name: Layer containing the cel frame_index: Frame index starting at 1 opacity: Opacity 0 (transparent) to 255 (opaque)

Inputs: filename (required), layer_name (required), frame_index (required), opacity (required).

set_cel_positionB

Set a cel's position in a specific layer and frame.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target frame_index: Frame index starting at 1 x: X position in pixels y: Y position in pixels create_if_missing: Create the cel if it does not exist source_frame_index: Optional frame to copy the cel image from

Inputs: filename (required), layer_name (required), frame_index (required), x (required), +3 more.

set_color_modeB

Convert the sprite's color mode.

Args: filename: Aseprite file to modify mode: "rgb", "grayscale", or "indexed"

Inputs: filename (required), mode (required).

set_frameB

Set the active frame by index (1-based).

Args: filename: Name of the Aseprite file to modify frame_index: Frame index starting at 1

Inputs: filename (required), frame_index (required).

set_frame_durationA

Set the duration of a frame in milliseconds.

Args: filename: Name of the Aseprite file to modify frame_index: Frame index starting at 1 duration_ms: Duration in milliseconds

Inputs: filename (required), frame_index (required), duration_ms (required).

set_frame_duration_allA

Set the duration of all frames in milliseconds.

Args: filename: Name of the Aseprite file to modify duration_ms: Duration in milliseconds

Inputs: filename (required), duration_ms (required).

set_layerA

Set the active layer by name.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to activate create_if_missing: Create layer if it does not exist

Inputs: filename (required), layer_name (required), create_if_missing.

set_layer_blend_modeA

Set a layer's blend mode.

Args: filename: Aseprite file to modify layer_name: Layer to modify mode: One of: normal, darken, multiply, color_burn, lighten, screen, color_dodge, addition, overlay, soft_light, hard_light, difference, exclusion, subtract, divide, hue, saturation, color, luminosity

Inputs: filename (required), layer_name (required), mode (required).

set_layer_opacityB

Set layer opacity by name (0-255).

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target opacity: Opacity value 0-255

Inputs: filename (required), layer_name (required), opacity (required).

set_layer_visibilityC

Set layer visibility by name.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target visible: Whether the layer should be visible

Inputs: filename (required), layer_name (required), visible.

set_onion_skinC

Configure onion skin settings for Aseprite.

Inputs: filename (required), enabled, before, after, +1 more.

set_paletteC

Set the active sprite palette using a list of hex colors.

Inputs: filename (required), colors (required).

set_slice_centerA

Set a slice's 9-patch center rectangle (relative to the slice origin).

The center defines the stretchable region for 9-patch scaling in game engines.

Args: filename: Aseprite file to modify name: Slice name x: Center-rect left edge, relative to the slice y: Center-rect top edge, relative to the slice width: Center-rect width height: Center-rect height

Inputs: filename (required), name (required), x (required), y (required), +2 more.

set_slice_pivotB

Set a slice's pivot point (relative to the slice origin).

Args: filename: Aseprite file to modify name: Slice name x: Pivot x, relative to the slice y: Pivot y, relative to the slice

Inputs: filename (required), name (required), x (required), y (required).

set_tagC

Create or update an animation tag on the sprite.

direction: forward | reverse | pingpong | pingpong_reverse

Inputs: filename (required), name (required), from_frame (required), to_frame (required), +1 more.

set_tilesA

Place tiles on a tilemap layer by grid position.

Args: filename: Aseprite file to modify layer_name: Tilemap layer to edit frame_index: Frame index starting at 1 tiles: List of {"col": int, "row": int, "tile_index": int} (col/row are grid coordinates; tile_index 0 clears the cell)

Inputs: filename (required), layer_name (required), frame_index (required), tiles (required).

start_preview_serverB

Start a simple HTTP server to preview exported sprites.

Args: directory: Directory to serve port: Port to bind (default 8000)

Inputs: directory (required), port.

stop_preview_serverA

Stop the preview HTTP server for a given port.

Args: port: Port to stop (default 8000)

Inputs: port.

tween_cel_opacity_easedC

Tween cel opacity with easing across a frame range.

Inputs: filename (required), layer_name (required), start_frame (required), end_frame (required), +5 more.

tween_cel_positionsB

Tween cel positions linearly across a frame range.

Args: filename: Name of the Aseprite file to modify layer_name: Layer name to target start_frame: Starting frame index (1-based) end_frame: Ending frame index (1-based, inclusive) start_x: Starting X position in pixels start_y: Starting Y position in pixels end_x: Ending X position in pixels end_y: Ending Y position in pixels create_missing_cels: Create missing cels during tween source_frame_index: Optional frame to copy the cel image from

Inputs: filename (required), layer_name (required), start_frame (required), end_frame (required), +6 more.

tween_cel_positions_easedB

Tween cel positions with easing across a frame range.

Inputs: filename (required), layer_name (required), start_frame (required), end_frame (required), +7 more.

tween_cel_scale_easedC

Tween cel scale with easing across a frame range.

Inputs: filename (required), layer_name (required), start_frame (required), end_frame (required), +7 more.

validate_sceneC

Validate presence of layers and cels across a frame range.

Returns JSON with missing layers and missing cels.

Inputs: filename (required), required_layers (required), start_frame, end_frame.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 113 tools

    Disambiguation3/5

    Several tools overlap in purpose, such as draw_circle vs draw_circle_at, adjust_hsl vs adjust_hsl_native, and outline_cel vs outline_native, which may confuse agents. The distinction between base and 'at' variants is clear but adds redundancy.

    Naming Consistency4/5

    Most tools follow a consistent verb_noun pattern in snake_case, e.g., add_frame, delete_layer, export_sprite. Minor deviations like animation_workflow_guide and get_sprite_info are acceptable but slightly break the pattern.

    Tool Count2/5

    With 113 tools, the server is overly large for typical MCP usage. Many tools are redundant (e.g., multiple tween and shape-drawing variants), suggesting the set could be streamlined to reduce cognitive load.

    Completeness4/5

    The tool set covers a wide range of pixel-art and animation operations, including layers, frames, palettes, tilemaps, and exports. Minor gaps exist (e.g., no bulk frame deletion), but overall the surface is comprehensive for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to create, inspect, edit, and export pixel art, sprites, animations, and spritesheets using headless Aseprite, and to convert arbitrary images into indexed pixel art.
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables AI assistants to create and edit pixel art and animated sprites in Aseprite through 104 tools covering drawing, layers, animation, palettes, tilemaps, exports, visual analysis, and raw Lua scripting.
      116
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to draw live in Aseprite, creating and editing sprites, using drawing tools, managing layers and frames, and viewing results as images.
      23
      137 npm
      11
      MIT