Aseprite Live

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 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 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:

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; nothi