Aseprite MCP Tools

Give AI assistants full control over Aseprite to create pixel art and animated sprites.

Unverified

stdio (local)

No auth

Python

View repo 205

Add to your client

Copy the config for your MCP client and paste it into its config file.

Paste into ~/Library/Application Support/Claude/claude_desktop_config.json

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

Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf

Before you start

Python 3.13+
uv package manager
Aseprite (set ASEPRITE_PATH in .env if it is not on your PATH)

About Aseprite MCP Tools

Aseprite MCP Tools is a Python MCP server that lets AI assistants create and edit pixel art and animated sprites by driving a real Aseprite installation in batch mode. It surfaces 104 tools across 17 categories — from canvas/layer/frame management and primitive drawing to higher-level pixel-art helpers like shading ramps, ordered dithering, outlines, retro palette presets, and quantization. For animation it offers cel lifecycle tools, eased position/opacity/scale tweens, oscillation, tags, and a visual-feedback loop (scaled frame exports, onion-skin renders, frame diffing, color statistics) so the model can inspect and correct its own work. A raw Lua escape hatch (run_lua_script) covers anything the dedicated tools don't. Exports cover PNG, GIF, sprite sheets, per-layer and per-tag output, plus a local HTTP preview server.

Tools & capabilities (94)

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).

draw_pixels

Plot individual pixels with per-pixel colors.

draw_pixels_at

Plot pixels on a specific layer/frame.

draw_line / draw_line_at

Draw lines with thickness.

draw_rectangle / draw_rectangle_at

Draw outlined or filled rectangles.

draw_circle / draw_circle_at

Draw outlined or filled circles.

draw_ellipse_at

Draw outlined or filled ellipses with separate x/y radii.

draw_polygon

Draw outlined or filled polygons from a point list.

draw_path

Draw a 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.

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.

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).

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 4x4 ordered dithering.

apply_dither_pattern

Uniform dithered mix of two colors at a given density.

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.

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-to-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.

flip_layer

Flip a cel horizontally or vertically.

rotate_layer

Rotate a cel 90/180/270 degrees.

resize_canvas

Scale the sprite to new dimensions.

crop_canvas

Crop to a rectangle.

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.

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_sprite

Export to PNG, GIF, JPG, and other formats.

export_frame

Export one frame as PNG with integer upscaling — the core visual-feedback loop: draw, export at 8x, 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.

get_pixel_color

Read one pixel's RGBA.

get_pixels_rect

Read a rectangle of pixels as JSON.

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.

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.

copy_layers_between_sprites

Copy layers by name from one .aseprite file to another.

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.

run_lua_script

Execute arbitrary Aseprite Lua in batch mode — the escape hatch when no dedicated tool fits. Runs unrestricted code on the host; only pass scripts you trust.

What this server can do

Aseprite MCP Tools provides tools for these capabilities — tap one to see every MCP server that does the same:

Generate images

When to use it

Have an AI assistant draw a still pixel-art character from a text prompt and export it upscaled.
Generate multi-frame sprite animations (e.g. an attack sequence) and export them as GIF or sprite sheets.
Plan and apply palettes — retro presets, hue-shifted shading ramps, and quantization — for consistent pixel art.
Iterate visually: export frames at high zoom, render onion skins, and diff frames so the model can correct its own work.
Build tilemaps and 9-patch slices for game assets.

Security notes

The `run_lua_script` tool executes arbitrary Aseprite Lua code on the host in batch mode — only pass scripts you trust. Several tools read and write `.aseprite` files and export images to the local filesystem.

Aseprite MCP Tools FAQ

Do I need Aseprite installed?

Yes. The server drives a real Aseprite binary in batch mode. Install Aseprite locally and set ASEPRITE_PATH in .env if it is not on your PATH, or run via the provided Docker image (which can install Aseprite via SteamCMD with Steam credentials).

How do I run it?

Add the mcpServers config block to your MCP client, pointing the uv command at the cloned repo directory and running `-m aseprite_mcp`. It requires Python 3.13+ and the uv package manager. A Docker image and docker-compose setup are also provided.

Is the raw Lua tool safe?

run_lua_script executes arbitrary, unrestricted Aseprite Lua on the host. Only pass scripts you trust.

What can it produce?

104 tools span drawing, layers, animation (eased tweens, oscillation, tags), palettes, effects, slices, tilemaps, and exports to PNG, GIF, and sprite sheets, plus analysis tools for visual feedback.

#aseprite #pixel-art #sprites #animation #design #image-generation #python #uv

Alternatives to Aseprite MCP Tools

Compare all alternatives →

Figma Context MCP (figma-developer-mcp)

Design & Media

15k

Popular community server that feeds Figma layout data to coding agents via a Figma API token.

Verified

stdio (local)

API key

TypeScript

2 tools

Updated 23 days agoRepo

21st.dev Magic MCP

Design & Media

5.2k

Generate beautiful, modern UI components from natural-language descriptions inside your IDE.

Unverified

stdio (local)

API key

TypeScript

4 tools

Updated 4 months agoRepo

Shadcn UI v4 MCP Server

Design & Media

2.8k

Give AI assistants full access to shadcn/ui v4 components, blocks, demos, and metadata across React, Svelte, Vue, and React Native.

Unverified

stdio (local)

API key

TypeScript

7 tools

Updated 1 month agoRepo

Compare Aseprite MCP Tools with:

vs Figma Context MCP (figma-developer-mcp)vs 21st.dev Magic MCP vs Shadcn UI v4 MCP Server vs MiniMax MCP Server (Official)