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.

Isometric primitives iso box → recessed port → tank → outline	Drawing suite rect · dithered gradient · ellipse · circle · dither · outline	Ramp-walk shading flat fill → volumetric, along a hand-ordered palette
Tilemaps tileset drawn tile by tile → map laid out row by row	Stamp painting one flower drawn once → scattered along an arc, one undo	The bridge panel live 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/; open them and Ctrl-Z backwards through the build.

Iso blockout, QA'd face polygons → recessed port · ramp + palette-locked shading · rivets stamped in one undo · qa_sweep 4/4

Beacon pulse additive glow · eased tween_cel_opacity loop · tagged + timed

Drone dash tween_frames smoothstep · smear_frame streak · endpoints verified with frame_diff

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:

_{render_onion_composite — 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/ 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"
      }
    }
  }
}

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: