Aseprite MCP Tools
Provides full control over Aseprite for pixel art and animation creation, including canvas, drawing, layers, animation, palettes, effects, slices, tilemaps, exports, and analysis tools.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Aseprite MCP Tools Draw a 32x32 pixel art character with a sword"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
6 | Create sprites, manage layers/frames, set the active state | |
14 | Pixels, lines, rectangles, circles, ellipses, polygons, paths, fills, gradients | |
7 | Delete, rename, duplicate, reorder, blend modes, merge, flatten | |
4 | Move, copy, and erase rectangular regions or colors | |
5 | Outlines, color replacement, HSL adjustment, ordered dithering | |
24 | Frames, cels, tags, tweening with easing, propagation | |
8 | Get/set palettes, retro presets, color ramps, quantization, color modes | |
4 | Flip, rotate, resize, crop | |
5 | Named regions, 9-patch centers, pivot points | |
5 | Tilemap layers, tileset editing, tile placement | |
7 | PNG, GIF, sprite sheets, per-layer/per-tag export, image import | |
3 | Read pixels and sprite metadata | |
3 | Onion-skin renders, frame diffing, color statistics | |
4 | Validate and sanitize animation consistency | |
1 | Copy layers between sprite files | |
3 | Local HTTP preview server, workflow guide | |
1 | Raw Lua escape hatch for anything not covered above |
Canvas
Tool | Description |
| Create a new sprite with the given dimensions |
| Add a new layer, optionally inside a named group |
| Add a new (optionally nested) group layer |
| Append a new frame |
| Set the active frame |
| Set one frame's duration in ms |
| 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 |
| Plot individual pixels with per-pixel colors |
| Plot pixels on a specific layer/frame |
| Lines with thickness |
| Outlined or filled rectangles |
| Outlined or filled circles |
| Outlined or filled ellipses with separate x/y radii |
| Outlined or filled polygons from a point list |
| Polyline through a point list with thickness |
| Paint-bucket flood fill |
| Smooth linear gradient fill in a rectangle |
Layers
Tool | Description |
| Delete a layer by name |
| Rename a layer |
| Duplicate a layer with all cels, opacity, and blend mode, optionally into a group |
| Move a layer to a position in the stack |
| Set blend mode (multiply, screen, overlay, ... 19 modes) |
| Merge a layer into the one below it |
| Flatten all layers into one |
Selection & Regions
Tool | Description |
| Cut a rectangle of pixels and paste it elsewhere |
| Copy a rectangle to another position, layer, or frame |
| Make a rectangle transparent |
| 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 |
| Add a 1px outline around all opaque pixels |
| Replace one color with another (with tolerance), preserving alpha |
| Shift hue/saturation/lightness of a cel — palette swaps, night scenes, shadows |
| Two-color gradient using Bayer 4×4 ordered dithering |
| Uniform dithered mix of two colors at a given density |
Animation
Tool | Description |
| Append N frames with optional duration |
| Delete a frame |
| Set every frame's duration |
| Duplicate a frame range N times |
| Copy all cels of a frame to other frames |
| Cel lifecycle on a layer/frame |
| Copy selected layers' cels across a frame range |
| Place a cel at x,y |
| Set a single cel's opacity |
| Shift cels by a delta across frames |
| Linear position tween across frames |
| Position tween with easing (ease_in/out, smoothstep) |
| Opacity tween with easing |
| Scale tween with easing and anchor |
| Sine-wave motion (bobbing, breathing, hovering) |
| Animation tags with direction (forward/reverse/pingpong) |
| Layer-level visibility and opacity |
| Configure onion-skin UI prefs (see |
| Sprite metadata: size, layers, frames, durations, tags |
Palette
Tool | Description |
| Read the palette as hex colors |
| Set the palette from a list of hex colors |
| List built-in retro palettes |
| Apply a preset: |
| Build a dark→light shading ramp with hue shifting from a base color |
| Snap every pixel to the nearest palette color |
| Remap specific colors across a frame range |
| Convert between RGB, grayscale, and indexed |
Transform
Tool | Description |
| Flip a cel horizontally or vertically |
| Rotate a cel 90/180/270° |
| Scale the sprite to new dimensions |
| Crop to a rectangle |
Slices
Tool | Description |
| Create a named rectangular region |
| Set the 9-patch stretchable center |
| Set the pivot point |
| List all slices with bounds, centers, pivots as JSON |
| Delete a slice |
Tilemap
Tool | Description |
| Add a tilemap layer with its own tileset and tile grid |
| Paint pixels into a tileset tile (auto-appends new tiles) |
| Place tiles on the map by grid position |
| Read which tile occupies a grid cell |
| Tile size, tile count, and map dimensions as JSON |
Export & Import
Tool | Description |
| Export to PNG, GIF, JPG, ... |
| Export one frame as PNG with integer upscaling — the core visual-feedback loop: draw, export at 8×, look, iterate |
| Sprite sheet (horizontal/vertical/rows/columns/packed) with optional JSON metadata and per-tag filtering |
| One PNG per layer |
| Export an animation tag as GIF or PNG sequence |
| Import a PNG into a layer (references, premade parts) |
| Duplicate the .aseprite file |
Inspection
Tool | Description |
| Read one pixel's RGBA |
| Read a rectangle of pixels as JSON |
| 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 a frame over translucent ghosts of neighboring frames — check motion continuity without opening Aseprite |
| Diff two frames: changed pixel count, percentage, bounding box |
| Color histogram of a frame — catches palette drift and near-duplicate colors |
Quality
Tool | Description |
| Create missing cels for layers across a frame range |
| Report missing layers/cels as JSON |
| Audit frames for overlaps and out-of-range layer activity |
| Normalize layer order, coverage, and overlaps |
Scene
Tool | Description |
| Copy layers by name from one .aseprite file to another |
Preview & Guide
Tool | Description |
| Serve exported files over local HTTP |
| Returns a step-by-step workflow guide for the LLM |
Scripting
Tool | Description |
| 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 |
Recommended Workflow for LLMs
Plan the palette first:
generate_color_rampfor each material (skin, armor, blade), orapply_palette_presetfor a retro look.Build in layers: background / body / equipment / effects, so parts can be animated and edited independently.
Draw coarse to fine: silhouette with
draw_rectangle_at/draw_ellipse_at/fill_area_at, then refine withdraw_pixels_at.Look at your work:
export_frameat 8×, inspect, fix, repeat. Useget_color_statsto keep the palette tight.Shade with intent:
adjust_hslfor shadow layers,apply_dither_gradientfor blends,outline_celfor readability.Animate with the cel tools:
propagate_cels, thentween_cel_positions_eased/oscillate_cel_positions; verify withrender_onion_skinandcompare_frames; export withexport_tag.
Docker Usage
Quick Start
Build and run the Docker image:
docker build -t aseprite-mcp:latest .
docker run -it --rm aseprite-mcp:latestOr use the provided build scripts:
Linux/macOS:
chmod +x build-docker.sh && ./build-docker.shWindows:
.\build-docker.ps1
Using Docker Compose
# Production
docker-compose up aseprite-mcp
# Development mode
docker-compose --profile dev up aseprite-mcp-devSee 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:latestIf 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+
uvpackage managerAseprite (set
ASEPRITE_PATHin.envif 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 toolsadd_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
Scored across 113 tools
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.
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.
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.
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
Related MCP Connectors
Generate pixel art sprites, animations, 8-direction rotations and palettes for games.
Generate, edit, style-match, turn, and animate game-ready pixel art at exact sizes.
Turn images into pixel art, extract and remap palettes, and upscale sprites without blur.
Generate game assets with AI for 2D games, including sprites, tilesets, and animations.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables AI assistants to control Aseprite for drawing and editing images through its API.59948MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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
- AlicenseBqualityCmaintenanceEnables 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.116MIT
- AlicenseAqualityBmaintenanceEnables AI assistants to draw live in Aseprite, creating and editing sprites, using drawing tools, managing layers and frames, and viewing results as images.23137 npm11MIT