aseprite-mcp

An MCP server that lets an AI assistant draw in Aseprite — live, in the real editor, on your canvas.

Gallery

<p align="center"> <img src="assets/gallery/demo.gif" width="600" alt="Live demo: Claude Code driving Aseprite over the MCP bridge, drawing a pixel-art portrait from a reference photo"><br> _{Live session — Claude Code drawing a pixel-art portrait in Aseprite} </p> <table align="center"> <tr> <td align="center" width="200"> <img src="assets/gallery/dog-walk.gif" width="128" alt="A pixel-art dog walk cycle" style="image-rendering: pixelated"><br> <em>Dog walk cycle</em><br> Opus 5 · Claude Code<br> _{Prompt: <em>"Make a dog walking sprite — a walk-cycle animation."</em>} </td> <td align="center" width="220"> <div style="white-space: nowrap"> <img src="assets/gallery/avatar-reference.jpg" width="90" alt="Reference photo used for the avatar"> → <img src="assets/gallery/avatar-pixel.png" width="90" alt="A pixel-art avatar portrait, drawn from the reference photo" style="image-rendering: pixelated"> </div> <em>Avatar portrait (from reference photo)</em><br> Opus 5 · Claude Code<br> _{Prompt: <em>"Here's a photo of me — can you draw a pixel-art avatar using it as reference?"</em>} </td> <td align="center" width="200"> <img src="assets/gallery/gold-duck.png" width="128" alt="A pixel-art rubber duck" style="image-rendering: pixelated"><br> <em>Rubber duck</em><br> gemma-4-26B-A4B-it-UD-Q4_K_XL · Pi Agent (local, RTX 3060 12GB)<br> _{Prompt: <em>"Draw a gold rubber duck."</em>} </td> </tr> </table>

Install

Two pieces: the server (Python, talks to your assistant) and the plugin (Lua, lives inside Aseprite). You need both. Aseprite 1.3 or newer.

1. The server

Point your MCP client at uvx — there is nothing to install ahead of time.

Claude Code:

claude mcp add aseprite -- uvx aseprite-mcp

Claude Desktop, or any client with a JSON config:

{
  "mcpServers": {
    "aseprite": {
      "command": "uvx",
      "args": ["aseprite-mcp"]
    }
  }
}

2. The plugin

Download aseprite-mcp.aseprite-extension from the latest release, then double-click it — or add it from Edit → Preferences → Extensions → Add Extension.

Restart Aseprite. Extensions load only at startup. Aseprite's console (View → Console) prints [MCP] Connected. once the bridge is up. Either end can start first; the plugin retries until the server is there and reconnects on its own afterwards.

From a clone

git clone https://github.com/giangdvdotdev/aseprite-mcp.git
cd aseprite-mcp
pip install -e ".[dev]"
python scripts/install_plugin.py    # build + install the plugin, then restart Aseprite

Usage

Open Aseprite and ask:

• "Draw me a 32×32 pixel-art fox."
• "Make it blink — duplicate the frame, close the eyes, 120ms each."
• "Export the spritesheet to ~/art/fox-sheet.png."

Thirty tools, all acting on Aseprite's active sprite: drawing (pixels, batches, lines, rects, ellipses, flood fill, erase), reading back (canvas image, pixels, regions, layers, selection), undo and redo, frames, open sprites, and PNG or spritesheet export.

→ Full tool reference

Configuration

The bridge runs on 127.0.0.1:9876. To move it, set ASEPRITE_MCP_PORT for both ends — nothing negotiates the port, and if only one side changes they never meet:

"env": { "ASEPRITE_MCP_PORT": "9877" }

Aseprite reads its environment at launch, so set the variable before starting the editor. Details per platform.

Troubleshooting

Nearly everything is one of three things: Aseprite is not running, the plugin was not installed or Aseprite was not restarted after installing it, or the two ends are on different ports.

→ Troubleshooting guide — every error message the tools produce, and what to do about it.

Security

The WebSocket listener is unauthenticated. It binds 127.0.0.1 only, so it is not reachable from other machines, but any process on your own machine can connect while the server is running and drive Aseprite through it. export_png, save_sprite, and export_spritesheet write to whatever absolute path they are given, overwriting what is there. If that is not acceptable in your environment, do not run the server.

Contributing

See CONTRIBUTING.md. Both test suites are fast and neither needs Aseprite running:

pytest                    # server
lua tests/lua/run.lua     # plugin

License

MIT.