Aseprite MCP Pro Max
Provides an MCP server that gives AI assistants full control over Aseprite, enabling pixel-art drawing, animation, shading, outlining, palette management, quality critique and polishing, checkpoints, and export workflows.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Aseprite MCP Pro Max
An MCP server that gives AI assistants full control over Aseprite — and, on top of that, the eye and the polish of a pixel-art lead.
156 tools: a complete drawing, animation and export toolkit, plus a quality layer that makes the art that comes out better, not just possible.
What you get | |
Sees its work |
|
Knows what's wrong |
|
Fixes it |
|
Shading |
|
Outlines |
|
Colour | perceptual OKLab/OKLCH ramps & palettes, |
Iteration |
|
Animation | frames, cels, tags, eased tweens, plus |
Conversion |
|
Shipping | PNG/GIF/sprite sheets, |
The Pro Max loop
The server tells the model this on connect, and pro_art_guide("workflow") spells it out:
save_checkpointbefore a big stepdo the step (draw flats,
outline_pro,auto_shade, …)view_quality— look at it the way an artist doescritique_sprite— fix the high issues, then the medium onescompare_versions— better? keep it. Worse?restore_checkpointpolish_spriteat the end of each stage. Aim for 90+ (grade A).
Example: flats → finished sprite
Flat colours drawn with draw_rows, then outline_pro(style="selective"), auto_shade(light_angle=135) and polish_sprite. Critique score 77 → 95. (script)
view_quality — what the model sees after each pass (1x/2x, zoom with problems marked, silhouette, values, palette):
Animated with squash_stretch, generate_particles("dust") and hit_flash, presented with export_showcase:
Quality tools
Critique & visual checks
Tool | Description |
| Score 0–100 and grade A–E with issues by severity, coordinates and the fixing tool: colour count for the size, near-duplicate colours, semi-transparency, value contrast, oversaturation, stray pixels, floating specks, jaggies (1-3-1 steps), L-shaped doubles on 1 px lines, outline coverage, flat fill, pillow shading, unclear light, banding, non-hue-shifted ramps, canvas-edge contact; across frames, palette drift |
| One image: 1x and 2x, a big zoom with problems outlined, silhouette, greyscale values and the palette sorted dark→light |
| The frame repeated in a grid plus a numeric seam report, for seamless tiles and textures |
| Motion critique: mechanical even spacing, sudden jumps, identical frames, pixel boil, volume changes, foot sliding, palette flicker, loop pops, uniform timing — plus a motion-path image |
Fixers
Tool | Description |
| Checkpoint, merge near-duplicate colours, pixel-perfect lines, remove strays, re-score — one call |
| Remove L-shaped doubles from 1 px lines (only line colours; fills and real corners are untouched) |
| Pixels no neighbour shares take the local colour; |
| Merge colours you can't tell apart (OKLab), across layers and frames; optional |
| Fixed, coloured or selective outlines, inside or outside, optionally on their own layer |
| Hand-style AA: single in-between pixels at the corners of long steps (inside the sprite, or against a known background) |
Shading & form
Tool | Description |
| Shade flat colours from one light: hue-shifted ramp per material (or yours), form from silhouette + parts, decals (spots, stripes) follow their host surface, contact shadows, optional rim light and dithered transitions; outline colours and small details are kept |
| Pixel-crisp normal map (OpenGL or DirectX convention) for 2D dynamic lighting in Godot/Unity |
Colour
Tool | Description |
| Perceptually even ramp in OKLCH: shadows cooler, lights warmer, chroma peaking in mid shadows |
| A cohesive palette — one ramp per material or a mood preset (fantasy, forest, desert, night, candy, sci-fi, horror, ocean, autumn, retro-warm), shared darks, optional neutrals; can apply it to a sprite |
| Near-duplicates, detected ramps and whether they hue-shift, uneven steps, lightness range, saturation — with advice |
| Extract a palette from reference art (weighted OKLab k-means) |
| Snap to a palette by perceived distance, with none / Bayer 2·4·8 / Floyd–Steinberg / Atkinson dithering |
Iteration
Tool | Description |
| Numbered versions with their critique scores, stored in |
| Before / now / changed-pixels image with both scores |
Animation polish
Tool | Description |
| Volume-preserving squash & stretch frames from one pose, anchored (feet stay on the ground) |
| Streak or solid smear frame between two poses, for fast swings and dashes |
| Damage flash or tint on chosen frames, keeping the outline |
| Hand-drawn-style dust, sparks, burst, sparkle, smoke and debris, deterministic per seed |
| Hair, capes and tails lag behind and overshoot the body's motion |
Conversion & transform
Tool | Description |
| Detect the real pixel grid of upscaled or AI "pixel art" (or scale a painting down by median sampling), remove a flat background, reduce colours perceptually, clean up, optional outline → a new .aseprite |
| Rotate by any angle with RotSprite (Scale2x ×3, rotate, sample back): unbroken lines, no new colours |
| Wrap-around shift, for fixing tile seams |
Export
Tool | Description |
| Presentation image: hero view, frames and palette on a background, with a title |
| PNG or GIF at any integer scale: nearest, Scale2x (EPX) or Scale3x; per-frame durations, transparency kept |
| Padding + edge extrusion (no bleeding), trimming with offsets, one row per tag, power-of-two, JSON metadata |
| The craft rules and which tool does each step: workflow, character, shading, lines, color, animation, environment, conversion |
Related MCP server: Aseprite MCP Tools
Core tools
Category | Tools | Description |
7 | Create sprites, manage layers/frames, set the active state | |
16 | Pixels, text rows, lines, rectangles, circles, ellipses, polygons, paths, fills, gradients, isometric boxes | |
3 | Draw and measure text with bitmap sprite-sheet or TrueType fonts | |
7 | Delete, rename, duplicate, reorder, blend modes, merge, flatten | |
4 | Move, copy, and erase rectangular regions or colors | |
12 | Outlines, color replacement, HSL adjustment, ordered dithering, native Aseprite filters | |
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 | |
8 | PNG, GIF, sprite sheets, per-layer/per-tag export, previews on a background, image import | |
6 | Read pixels (one layer, the visible composite, or as text rows) and sprite metadata | |
6 | Sprite previews the model can see, onion-skin renders, frame diffing, bounds, lint, 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.
draw_rows(filename="mug.aseprite", layer_name="mug", frame_index=1, x=4, y=2,
rows=[".WWWW..",
".WWWWKK",
".WWWW.K",
"..WW.K."],
legend={"W": "#F4F4F4", "K": "#8B5A2B"}, outline="#1A1C2C"). (or any character missing from the legend) leaves a pixel untouched; read_rows returns pixels in the same format, so an edit is read, change a few characters, draw again.
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 |
| Pixels as rows of characters plus a colour legend, like ASCII art, with an optional 1px outline — the compact way to place hand-chosen detail (faces, hands, animals, handles) |
| Solid 2:1 isometric box with clean 2-1 edges and a colour per face, for furniture and props |
Text
Aseprite's Lua API has no text drawing, so glyphs are rasterised on the server and composited into the sprite. Two font backends are supported: bitmap sprite-sheet fonts (the right choice for pixel art — glyphs are already pixels and size scales them by whole numbers) and TrueType .ttf/.otf files, rendered without antialiasing unless you ask for it.
Fonts are discovered in ~/.aseprite-mcp/fonts: a bitmap font is a directory containing font.json plus its sheet PNGs; a TrueType font is just the font file. Installed system fonts are listed too. font also accepts a direct path.
Tool | Description |
| List the bitmap and TrueType fonts available to |
| Width, height, advance and baseline extents — size a panel or centre a label without redrawing to find out |
| Draw text with anchors, faux bold, outline, drop shadow and letter spacing |
Call measure_text first when the layout depends on the text: it returns the same metrics draw_text will use, so a label can be centred or a plate sized in one pass.
measure_text(text="MODERATOR", font="minecraft", size=2, bold=1)
-> width=115 height=15 advance_width=117 above_baseline=14 below_baseline=1 left_bearing=0
draw_text(filename="badge.aseprite", text="MODERATOR", x=64, y=17,
font="minecraft", size=2, anchor="baseline", bold=1,
color="#FFFFFF", shadow_color="#14237A")Anchors are topleft/top/topright, left/center/right, bottomleft/bottom/bottomright, plus baselineleft/baseline/baselineright for pinning several labels to one baseline. Outline and shadow grow the stamp but never move the glyphs.
font.json
{
"name": "my-font",
"letter_gap": 1,
"space_width": 3,
"sheets": [{
"file": "sheet.png",
"cell_w": 8, "cell_h": 8,
"ascent": 7,
"chars": [" !\"#$%&'()*+,-./", "0123456789:;<=>?"]
}],
"overrides": {
"86": {"ascent": 7, "rows": ["#...#", "#...#", ".#.#.", "..#.."]}
}
}Each sheet carries its own ascent, so sheets with different cell sizes still share a baseline — that is how a compact ASCII sheet and a taller accented sheet combine into one run. origin shifts the cell grid when the sheet has a margin, ink_rule: "dark" reads sheets that use an opaque white background to delimit variable-width glyph boxes, and advance: "box" takes the advance from the box rather than the ink. overrides replaces individual glyphs with hand-drawn rows, which is useful when a sheet ships a glyph that is off-centre or too tall to sit on the line.
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, or only around the shapes in a region |
| 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 |
Native filters run Aseprite's own engine commands on a layer and frame:
Tool | Description |
| Aseprite's Outline command around opaque pixels |
| Aseprite's Hue/Saturation/Lightness filter |
| Brightness/Contrast filter |
| Colour inversion |
| Convolution filter: blur, sharpen, edge, emboss … |
| List the built-in matrices for |
| Build an optimal palette from the sprite (native colour quantization) |
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 (to look at your work, use |
| 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 |
| GIF or PNG sequence of every frame or one tag, scaled, optionally on a solid background — the sprite itself is never changed |
| 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 |
| Read what is visible (all layers composited) at a pixel or over a rectangle |
| Read a region as rows of characters plus a legend — the compact format |
| Sprite metadata (also listed under Animation) |
Analysis & Visual Feedback
Batch-mode equivalents of what a human artist gets from the Aseprite UI.
Tool | Description |
| Return an image of the frames straight to the model — zoomed, with pixel grid and coordinate rulers so it can fix exact pixels |
| Render a frame over translucent ghosts of neighboring frames — check motion continuity without opening Aseprite |
| Diff two frames, optionally one layer or region (did the feet move?): changed pixel count, percentage, bounding box |
| Bounding box of the drawn pixels per frame, optionally one layer — measure rise and fall, ground line, canvas edges |
| Detached pieces, lone pixels and orphan pixels, with coordinates |
| Color histogram of a frame — catches palette drift and near-duplicate colors |
view_sprite is the drawing loop's eyes: it returns the picture as MCP image content, so the model sees its work without exporting a file and opening it, and works in clients that cannot read local files. Pick frames with "3", "1-4" or "1,3,6-8", layer_name to isolate one layer, and region="x,y,w,h" to zoom into a detail with rulers still in sprite coordinates.
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 |
| How to animate well: key poses, anticipation, squash and stretch, timing ( |
The server also sends short pixel-art rules as MCP instructions when a client connects (silhouette first, one light direction, clean lines, check each pass), so the model gets them without calling anything.
Scripting
Tool | Description |
| Execute arbitrary Aseprite Lua (API docs) in batch mode. The last resort, for what no dedicated tool covers: 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_rows.Look at your work:
view_spriteafter every pass (regionto zoom in), fix, repeat. Useget_color_statsto keep the palette tight andlint_spriteto catch stray and detached pixels.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 withview_sprite,compare_framesandget_bounds; export withexport_animationorexport_tag.
Docker Usage
Quick Start
Build and run the Docker image:
docker build -t aseprite-mcp-pro-max:latest .
docker run -it --rm aseprite-mcp-pro-max: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-pro-max
# Development mode
docker-compose --profile dev up aseprite-mcp-pro-max-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-pro-max: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)
Dependencies (mcp, numpy, pillow, httpx) are installed by uv sync. It needs mcp 1.x: MCP 2.x renamed FastMCP, so the dependency is pinned below 2.
An Aseprite run that takes longer than 60 seconds is stopped and reported as an error. Set ASEPRITE_TIMEOUT_SECONDS in .env to change that limit.
Installation
git clone https://github.com/Layfate/aseprite-mcp-pro-max.git
cd aseprite-mcp-pro-max
uv syncThen add the server to your MCP client:
{
"mcpServers": {
"aseprite-pro-max": {
"command": "/opt/homebrew/bin/uv",
"args": [
"--directory",
"/path/to/repo",
"run",
"-m",
"aseprite_mcp"
]
}
}
}Running the tests
The tests drive a real Aseprite (ASEPRITE_PATH in .env):
uv run pytest -qDeveloped and tested against Aseprite 1.3.18.6 in headless batch mode.
License
MIT, see LICENSE. Made by Zense. Includes code from aseprite-mcp (MIT, © 2024 Divyansh Singh). Algorithms: OKLab by Björn Ottosson, Scale2x/Scale3x by Andrea Mazzoleni, RotSprite by Xenowhirl.
Aseprite is a separate product by Igara Studio and is not included; you need your own copy.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Generate, edit, style-match, turn, and animate game-ready pixel art at exact sizes.
Pixel art for your game, from your coding agent. Generate sprites, items and tiles in your game's style (64 to 1024 px), make variants, reskins and N/E/S/W directions, then edit everything in a full pixel art editor that syncs into your project. Works with Claude, Claude Code, Cursor and ChatGPT; sign in with OAuth, no API key.
Turn images into pixel art, extract and remap palettes, and upscale sprites without blur.
Generate pixel art sprites, animations, 8-direction rotations and palettes for games.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI sprite generation and semantic tools for Aseprite, allowing LLMs to create pixel art, add animations, and manage projects with visual feedback.61GPL 3.0
- AlicenseCqualityDmaintenanceEnables AI assistants to control Aseprite for creating pixel art and animated sprites, with 104 tools covering canvas, drawing, animation, palettes, effects, and more.100MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to drive Aseprite for pixel-art creation, including sprite setup, grid-based drawing, layer/frame/tag management, reference image import, and export, with rendered previews after every mutation.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