Aseprite Live Mcp

aseprite-live-mcp

[](https://pypi.org/project/aseprite-live-mcp/) [](https://pypi.org/project/aseprite-live-mcp/) [](https://github.com/oaktreegames/aseprite-live-mcp/actions/workflows/ci.yml)

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

Isometric primitivesiso box → recessed port → tank → outline Drawing suiterect · dithered gradient · ellipse · circle · dither · outline Ramp-walk shadingflat fill → volumetric, along a hand-ordered palette

Tilemapstileset drawn tile by tile → map laid out row by row Stamp paintingone flower drawn once → scattered along an arc, one undo The bridge panellive status, activity log, a Pause toggle — in Aseprite

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/](examples/showcase/); open them and Ctrl-Z backwards through the build.

Iso blockout, QA'dface polygons → recessed port · ramp + palette-locked shading · rivets stamped in one undo · qasweep 4/4 Beacon pulseadditive glow · eased tweencelopacity loop · tagged + timed Drone dashtweenframes smoothstep · smearframe streak · endpoints verified with framediff

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:

renderonioncomposite — earlier frames red, later frames blue, the whole arc in one image

The sheet's ten slices went to Unity in one action — [examples/showcase/unity/](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).

[](https://insiders.vscode.dev/redirect/mcp/install?name=aseprite-live&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22aseprite-live-mcp%22%5D%7D) [](https://cursor.com/install-mcp?name=aseprite-live&config=eyJjb21tYW5kIjoidXZ4IGFzZXByaXRlLWxpdmUtbWNwIn0%3D)

Claude Code

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

Claude Desktop / any JSON-config client

{
  "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.

From source

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](asepriteclient/claude-bridge.lua) and [relay_server.py](bridge/relayserver.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`).

1. Start the relay: python bridge/relay_server.py (needs pip install websockets).
2. 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.

1. 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](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.

Inspect & metadata (6)

• 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'.

Documents & session (5)

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

Canvas (3)

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

Layers & groups (14)

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

Frames (8)

• 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 [fromframe..toframe] to `ms` milliseconds.
• reverse_frames — Reverse frame order (cels on every layer, plus durations) — the whole sprite by default, or the inclusive [fromframe..toframe] 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.

Cels (3)

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

Drawing (10)

• 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 (centerx, centery).
• fill_area — Flood-fill the contiguous same-color region at (x, y).
• draw_ellipse — Draw an ellipse centered at (centerx, centery) 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.

Palette (12)

• 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 extens

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: oaktreegames
• Source: oaktreegames/aseprite-live-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.