aseprite-live-mcp

Let an AI agent draw in your live Aseprite editor — every edit one named undo — with a Unity-first, game-dev toolset.

An open-source Model Context Protocol server for Aseprite. It drives your running editor (all open documents, unsaved tabs, in-editor dialogs, even asking you to click a point on the canvas) and runs headless (aseprite --batch) against files on disk. One-action Unity sprite-sheet + .meta export with per-slice pivots, a project-convention art-QA sweep, isometric primitives, tilemaps, and a server that tells you when it's out of date.

See it in action

Each of these is an AI agent driving a live Aseprite canvas through the MCP — one named undo per step.

And the part no headless server can do — the agent asking you, inside your editor (a real screen capture, not a mockup):

A full set, one live session

Everything below came out of a single session against one running editor: five sprites built, QA'd, assembled into a sheet, sliced, and exported for Unity — finished with an in-editor approval dialog. The .aseprite sources are in examples/showcase/; open them and Ctrl-Z backwards through the build.

The QA tools aren't decoration. During this build, frame_diff's change bbox caught a motion tween the eye missed — every cel displaced by its image origin and clipping at the canvas edge. One transaction fixed it; the same diff re-verified it:

The sheet's ten slices went to Unity in one action — examples/showcase/unity/ has the atlas PNG and its generated .meta: ten Multiple-mode sprites, rects y-flipped, every pivot baked.

Install

One command, no clone:

uvx aseprite-live-mcp        # or: pipx run aseprite-live-mcp

Requires Python 3.10+ and Aseprite 1.3+. That's it for headless; the live editor needs one extra step (below).

claude mcp add aseprite-live -- uvx aseprite-live-mcp

{
  "mcpServers": {
    "aseprite-live": {
      "command": "uvx",
      "args": ["aseprite-live-mcp"],
      "env": {
        "ASEPRITE_MCP_BACKEND": "headless",           // or "live" — see below
        "ASEPRITE_PATH": "C:/Program Files/Aseprite/Aseprite.exe"
      }
    }
  }
}

ASEPRITE_PATH is auto-detected on common installs (Steam and standalone) if you omit it.

git clone https://github.com/oaktreegames/aseprite-live-mcp
cd aseprite-live-mcp
pip install -e .

Quickstart — headless (2 minutes, no editor open)

Add the server with "ASEPRITE_MCP_BACKEND": "headless" (above). In headless mode, tools take a file argument — the .aseprite to act on. Ask your agent to run status to confirm the connection, then try:

"Create a 32×32 sprite at C:/art/coin.aseprite, draw a gold circle, and export it as coin.png."

Quickstart — live editor (drive your open canvas)

The live backend edits your running Aseprite, one undo step per edit. The bridge script and relay live in this repo (they're not in the pip package), so grab them first: git clone https://github.com/oaktreegames/aseprite-live-mcp — or download just claude-bridge.lua and relay_server.py.

1. Install the bridge script into Aseprite — in Aseprite, File → Scripts → Open Scripts Folder, copy aseprite_client/claude-bridge.lua into it, and restart Aseprite (or File → Scripts → Rescan Scripts Folder).
2. Start the relay: python bridge/relay_server.py (needs pip install websockets).
3. Connect: in Aseprite, File → Scripts → claude-bridge, and grant the script trust when asked. The panel shows "connected to Claude", live activity, and a Pause toggle.
4. Switch the backend to live in your MCP config ("ASEPRITE_MCP_BACKEND": "live").

Now tools act on your active document; watch edits appear and press Ctrl-Z to undo each one. See docs/ARCHITECTURE.md for how it works.

What you can ask it to do

• "Make a 32×32 sprite, draw a red circle, and export it as icon.png."
• "Export machines.aseprite as a Unity sprite sheet at 16 pixels-per-unit." → drops a sheet + a pre-sliced .meta straight into your Unity project.
• "Slice this atlas, set each slice's pivot, and export it to Unity with the pivots baked in."
• "Run a QA sweep: it must be 64×64, ≤ 16 colors, grid-aligned, with 2px of sticker padding."
• "Draw an isometric box for a 1×1 machine base and put a recessed port on its front face."
• "Set up a 16×16 tilemap layer, draw grass and dirt tiles, and lay out a 10×6 ground strip."
• "Assemble my exports into one labeled sheet, slice each piece, set the pivots, and hand Unity the atlas."
• "Pop a dialog in my editor: approve or redo. Then wait for me to click the anchor point."
• "Watch the sprite while I touch it up; when I stop, re-run the QA sweep."
• "Diff frames 3 and 4 — did the arm actually move?"

Where this sits (honest positioning)

There are already good Aseprite MCP servers. This project is not the first, and doesn't claim to be. What it claims — and can defend:

Capability	Landscape	This project
Draw / layers / frames / palette / selection / export, dithering, gradients, outlines, filters, tweens, tilemaps	Well covered by the headless leaders (diivi ~113 tools, pixel-mcp, ext-sakamoro) and the commercial live server (Aseprite MCP Pro, Godot-first)	Parity — a curated, fully typed surface
One-action Unity export — sheet + .meta with per-slice pivots baked in	Every other Aseprite→Unity path we found is a separate engine-side importer; none export pivots	Differentiator ✅
Art-QA sweep incl. transparent sticker-padding measurement against your project conventions	We found no other server that lints sprite margins/padding as a packaged sweep	Differentiator ✅
Isometric drawing primitives (2:1 boxes/cylinders, auto face-shading, recessed panels)	The only iso primitives we've found in any Aseprite MCP we surveyed	Differentiator ✅
In-editor interaction: dialogs in Aseprite, ask-the-artist point picking, artist-edit watching, symmetry & viewport control	Live-GUI servers exist (Pro commercial; two nascent OSS); none we surveyed ship in-editor dialogs or human-in-the-loop tools	Differentiator ✅
Update awareness — the server itself tells you when a newer release exists	As far as we could find (checked 2026-07-16), no other MCP server surfaces its own update status through the session	Differentiator ✅
Live tilemap editing	The headless leaders edit tilemaps on disk; the only live tilemap editing we found is closed-source	Open-source position ✅
MCP resources + prompts	Across the open-source Aseprite MCPs we surveyed, this is the richest MCP-native surface (live-state resources + guided-workflow prompts)	Differentiator (hedged)

Every edit made through the server is exactly one named undo step (app.transaction) — you can watch an agent work and Ctrl-Z anything it did, one step at a time. We verified the other open-source live bridges don't hold that discipline across their surface (one wraps 3 of 57 tools).

Knowing when to update

The status tool reports the server's version and — at most once a day, via PyPI — whether a newer release exists. Your agent sees it, so you see it:

{ "backend": "live", "connected": true,
  "server": { "current": "0.2.0", "latest": "0.2.1", "update_available": true,
              "how": "pip install -U aseprite-live-mcp (uvx users: run uvx aseprite-live-mcp@latest once — uvx reuses its cached version otherwise)" } }

Also surfaced as the aseprite://update resource, one stderr log line, and the real version in the MCP serverInfo handshake. Disable with ASEPRITE_MCP_NO_UPDATE_CHECK=1 (auto-disabled in CI). No telemetry — the check is an HTTP GET of PyPI's public JSON; nothing about you, your machine, or your art is sent.

Tools (139)

Every tool is typed, annotated (readOnlyHint/destructiveHint/idempotentHint/openWorldHint), and — when it mutates — wrapped in a named app.transaction, so each edit is exactly one labeled undo step in the editor.

• status — Report backend health plus this server's version and whether a newer release exists.
• get_sprite_info — Get the active sprite's size, color mode, and layer/frame/tag lists.
• get_pixel — Read one composited pixel (all layers) at (x, y) as #rrggbbaa.
• set_sprite_metadata — Attach typed key/value metadata to the sprite (Aseprite's Properties system — stored in the .aseprite file itself).
• get_sprite_metadata — Read the sprite's typed key/value metadata (Properties).
• get_pixels — Read a composited pixel region as a grid of #rrggbbaa strings — the AI feedback loop for 'what does the canvas look like now'.

• open_sprite — Open a sprite file and make it the active document; returns its filename, size, and frame/layer counts.
• save_sprite — Save the active sprite to disk: to path if given (save-as; the document's filename follows it), else to its own filename — errors if the sprite is untitled and no path is given.
• close_sprite — Close the active sprite.
• set_active_sprite — Live editor only: make one of the open documents active, found by exact filename or basename match (e.g. "turret.aseprite").
• list_sprites — Live editor only: list every open document — filename (or "(unsaved)"), size, frame/layer counts, unsaved-changes flag, and which one is active.

• create_sprite — Create a new sprite.
• expand_canvas — Grow (or shrink, with negatives) the canvas per side WITHOUT scaling content — existing pixels keep their positions relative to the old origin.
• import_spritesheet — Slice a sheet PNG into animation frames: cells are read row-major at the given frame size onto a new "imported" layer, adding frames as needed.

• add_layer — Add a new empty layer (optionally named) at the top of the stack.
• add_group — Add a layer group.
• move_layer_to_group — Move a layer inside a layer group.
• list_layers — The full layer tree, top of stack first: name, path, kind (image/group/tilemap), visibility, and opacity — including layers nested in groups (which get_sprite_info lists only at the top level).
• delete_layer — Delete the layer with the given name.
• rename_layer — Rename a layer.
• set_layer_visibility — Show or hide a layer.
• set_layer_opacity — Set a layer's opacity (0-255).
• flatten_sprite — Flatten all layers into a single layer.
• set_layer_blend_mode — Set a layer's blend mode.
• duplicate_layer — Duplicate a layer (with its cels) above the original.
• merge_layer_down — Merge a layer into the layer directly beneath it.
• move_layer — Reorder a layer in the stack.
• import_image_as_layer — Import an external image file (PNG, etc.) into a new layer at (x, y) — a reference/trace layer for concept-art intake.

• add_frame — Append a new empty frame.
• duplicate_frame — Duplicate frame number (1-based).
• delete_frame — Delete frame number (1-based).
• set_frame_duration — Set frame number's duration in milliseconds.
• add_frames — Append count empty frames in one undo step.
• set_frame_durations — Set every frame in [from_frame..to_frame] to ms milliseconds.
• reverse_frames — Reverse frame order (cels on every layer, plus durations) — the whole sprite by default, or the inclusive [from_frame..to_frame] range.
• set_onion_skin — Configure the editor's onion-skin view: on/off, ghost counts each direction, and whether ghosting stays inside the current tag.

• clear_cel — Empty the cel at the given layer + frame (transparent).
• set_cel_position — Move the cel's top-left origin to (x, y).
• set_cel_opacity — Set the cel's opacity (0-255).

• draw_pixels — Set individual pixels: pixels is a list of {"x": int, "y": int, "color": "#rrggbb[aa]"}.
• draw_polyline — Stroke connected line segments through points (ordered [x, y] pairs); close=True joins the last point back to the first.
• draw_rectangle — Draw a rectangle on the active layer + frame.
• draw_line — Draw a 1px line from (x1,y1) to (x2,y2).
• draw_circle — Draw a circle centered at (center_x, center_y).
• fill_area — Flood-fill the contiguous same-color region at (x, y).
• draw_ellipse — Draw an ellipse centered at (center_x, center_y) with independent x/y radii.
• draw_gradient — Fill a rectangle with a linear gradient from color1 to color2.
• apply_dither — Fill a rectangle with a uniform ordered (Bayer 4x4) dither mixing color1 and color2.
• add_outline — Add a 1px outline in color around the opaque pixels of the active cel — readability against busy backgrounds.

• get_palette — Return the active sprite's palette as #rrggbbaa hex strings.
• set_palette_color — Set palette entry index to color (#rrggbb or #rrggbbaa).
• add_palette_color — Append color to the palette and return its new index.
• set_palette — Replace the whole palette with colors (list of #rrggbb/#rrggbbaa).
• apply_preset_palette — Replace the palette with a built-in preset: gameboy | pico8 | cga.
• generate_color_ramp — Generate a dark->light shading ramp from base_color and APPEND it to the palette in order — ready for palette_ramp_walk.
• extract_palette_from_image — Extract a palette (median-cut) from an external image file and, by default, set it as the active sprite's palette — the concept-art → locked-palette step.
• sort_palette — Reorder palette swatches by luminance (default), hue, or saturation.
• palette_from_sprite — Derive the palette FROM the sprite's actual pixels (Aseprite's color quantization) — the inverse of quantize_to_palette.
• load_palette — Replace the sprite's palette from a palette file (.gpl, .pal, .ase, .png strip — anything Aseprite reads).
• save_palette — Write the sprite's palette to a file (.gpl, .pal, .png — by extension).
• apply_bundled_palette — Apply one of Aseprite's bundled extension palettes by resource ID — e.g. DB16, DB32, ARQ4, EDG16 (availability depends on the installed palette extensions).

• replace_color — Replace every pixel matching from_color (within tolerance, a 0-255 RGB distance) with to_color across the active cel, preserving each pixel's alpha unless to_color carries its own.
• quantize_to_palette — Snap every opaque pixel of the active cel to its nearest color in the sprite's palette (alpha preserved) — enforce palette discipline after intake or shading.
• adjust_hsl — Shift the active cel's colors in HSL: hue_shift degrees (-360..360), saturation a multiplier (1.0 = unchanged), lightness a delta (-1..1).
• get_color_stats — Return a color histogram of the composited sprite: distinct opaque color count, total opaque pixels, and the top most-used colors with counts — a palette-drift check for the art-QA loop.

• apply_shading — Palette-constrained shading: brighten toward the light and darken away from it, snapping every pixel to the nearest palette color.
• palette_ramp_walk — Shade by WALKING the arranged palette ±N indices toward lighter/darker (per light direction), instead of snapping to the luminance-nearest color — so hand-ordered shading ramps are respected.

• adjust_brightness_contrast — Adjust the active cel's brightness and contrast, each -100..100 (0 = unchanged).
• invert_colors — Invert the active cel's RGB (alpha untouched).
• desaturate — Convert the active cel to grayscale (Rec. 601 luma), keeping alpha.
• box_blur — Blur the active cel with an alpha-weighted box kernel.
• sharpen — Sharpen the active cel (unsharp mask over a 3x3 neighborhood).

• paint_with_stamp — Stamp an image at each [x, y] in points (points are stamp centers).

• draw_iso_box — Draw a 2:1 isometric box.
• draw_iso_cylinder — Draw a vertical isometric cylinder (tank/silo/chimney): top ellipse + shaded body + front rim, auto-shaded from color.
• fill_polygon — Scanline-fill an arbitrary polygon given points (a list of [x, y] pairs, in order).
• iso_recessed_panel — Draw a recessed docking socket/port on an isometric face — a light lit lip framing a dark recessed interior.

• select_rectangle — Set a rectangular selection.
• select_all — Select the whole canvas.
• deselect — Clear the current selection.
• select_ellipse — Select an ellipse inscribed in the given rectangle.
• select_by_color — Select every pixel matching color (composited, within tolerance 0-255 per channel) — a global magic wand.
• invert_selection — Invert the current selection against the canvas bounds.
• get_selection — Report whether a selection exists and its bounding rectangle.
• erase_area — Erase pixels to transparent.

• flip_sprite — Flip the whole sprite horizontally or vertically.
• resize_sprite — Scale the whole sprite to new pixel dimensions.
• crop_sprite — Crop the sprite to the given rectangle.
• rotate_sprite — Rotate the whole sprite by 90, 180, or 270 degrees clockwise (lossless).
• autocrop_sprite — Trim transparent borders: shrink the canvas to the union of visible content across all layers and frames (Sprite > Trim).
• set_color_mode — Convert the sprite between rgb | gray | indexed color modes.

• create_slice — Create a named slice (atlas region) at the given rectangle.
• set_slice_pivot — Set a slice's pivot point, in pixels relative to the slice's top-left.
• set_slice_center — Set a slice's 9-patch stretchable center rectangle (relative to the slice).
• list_slices — List every slice with its bounds, pivot, and 9-patch center.
• delete_slice — Delete the slice with the given name.