Aseprite MCP

An extensive Model Context Protocol server that lets an AI agent (Claude Code, Claude Desktop, or any MCP client) create and edit Aseprite sprites — draw pixel art, build animations, manage layers/frames/tags/palettes, and export to PNG/GIF/sprite sheets — all headlessly.

📖 Full tool reference: docs/TOOLS.md — every tool with its parameters.

It works by generating Lua scripts and running them through Aseprite's batch mode (aseprite -b --script ...), plus the Aseprite CLI for exports. Every operation opens a real .aseprite file, edits it, and saves — so your files stay fully editable in the Aseprite GUI.

• 98 tools across sprites, layers, frames, cels, drawing (incl. pixel-perfect & anti-aliased modes), custom brushes & symmetry, palettes (extract/sort/ramps), animation tags, slices/9-patch, effects (gradients/outline/drop-shadow/colour adjustments), text rendering, tilemaps, image stamping, reference/rotoscope layers, transforms, rich export (per-layer/per-tag, sprite sheets, onion-skin), and a GUI companion view.

• Structured results — every tool returns JSON describing the updated sprite.

• render_preview returns a PNG so the agent can see its work and self-correct.

• Deterministic, stateless, robust — each call is an isolated, headless Aseprite run.

Showcase

Everything below was produced entirely through MCP tool calls — no manual pixel-pushing — exercising drawing, shading, outlines, animation, tilemaps, and palette generation.

Related MCP server: LibreSprite MCP

Requirements

• Aseprite 1.3+ (the scripting API). The Steam and standalone builds both work.

• Python 3.10+

• uv (recommended) — or any PEP 517 installer.

Install

git clone https://github.com/MalloyTheDev/aseprite-mcp.git
cd aseprite-mcp
uv sync

That creates a virtual environment and installs the aseprite-mcp package and its dependencies. Verify it can find Aseprite and run the test suite (tests auto-skip if Aseprite isn't found):

uv run pytest

Configuration

Everything is configurable via environment variables (all optional):

On this machine Aseprite was detected at C:\Program Files (x86)\Steam\steamapps\common\Aseprite\Aseprite.exe, so ASEPRITE_PATH is not strictly required — but setting it explicitly is the most reliable.

Register with an MCP client

Replace /ABSOLUTE/PATH/TO/aseprite-mcp below with the absolute path to your clone.

Claude Code (CLI)

claude mcp add aseprite -- uv --directory /ABSOLUTE/PATH/TO/aseprite-mcp run aseprite-mcp

To set the Aseprite path explicitly (recommended if auto-detection fails):

claude mcp add aseprite \
  --env ASEPRITE_PATH="/path/to/Aseprite.exe" \
  -- uv --directory /ABSOLUTE/PATH/TO/aseprite-mcp run aseprite-mcp

Claude Desktop / generic MCP client (JSON)

Add this to your client's MCP server config (e.g. claude_desktop_config.json). A ready-to-copy template lives in mcp-config.example.json (Windows-style paths shown — adjust for your OS):

{
  "mcpServers": {
    "aseprite": {
      "command": "uv",
      "args": ["--directory", "C:\\path\\to\\aseprite-mcp", "run", "aseprite-mcp"],
      "env": {
        "ASEPRITE_PATH": "C:\\Program Files (x86)\\Steam\\steamapps\\common\\Aseprite\\Aseprite.exe",
        "ASEPRITE_MCP_WORKSPACE": "C:\\path\\to\\aseprite-mcp\\workspace"
      }
    }
  }
}

Restart the client; the aseprite server and its 98 tools will be available.

Tool catalogue

Relative filenames resolve inside the workspace; absolute paths are honoured. Frames and palette-aware operations are 1-based for frames, 0-based for palette indices. Colours accept #RRGGBB, #RRGGBBAA, r,g,b, r,g,b,a, index:N, or a name (black, white, red, green, blue, yellow, cyan, magenta, transparent, …).

Sprite lifecycle

Inspection & preview

Layers

Frames (animation)

Cels (a layer's image at a frame)

Animation tags

Drawing

Brushes & symmetry

Slices (named regions / 9-patch)

Effects & colour adjustments

Text

Tilemaps (Aseprite 1.3+)

Image stamping

Palette

Transform & export

Reference / rotoscope

GUI companion mode

Live viewing (GUI companion mode)

The server edits files headlessly, but you can watch the work in the real Aseprite window. Call open_in_editor("sprite.aseprite") and Aseprite opens it in a normal, non-blocking window. As the agent keeps saving edits with the other tools, Aseprite detects the on-disk change and offers to reload (or reloads automatically, depending on your Aseprite preferences) — so edits appear without re-opening.

What this is and isn't: Aseprite's Lua scripting sandbox has no networking or timers, so the server can't stream a live canvas into the GUI frame-by-frame. The companion view above (open once → headless edits → Aseprite reloads) is the robust, supported workflow. The agent's own "eyes" remain render_preview, which returns a PNG it can inspect directly.

Example agent workflow

"Make me a 32×32 walking-slime animation."

1. create_sprite("slime.aseprite", 32, 32, "rgb")

2. fill_layer the background, add_layer("slime"), draw the body with draw_ellipse/fill_area/draw_pixels.

3. add_frame(copy_from=1) a couple of times; nudge the body with set_cel_position to create a bounce.

4. set_all_frame_durations(120) and add_tag("walk", 1, 3, "pingpong").

5. render_preview to check it, iterate, then export_gif("slime.gif", scale=8).

How it works

client (Claude) ──MCP──> aseprite-mcp (FastMCP, Python)
                              │  builds a Lua body + ARG table
                              ▼
                         luagen.assemble_script  ──>  temp .lua
                              │   (prelude: JSON encoder, colour/pixel
                              │    helpers, drawing primitives, info)
                              ▼
                  Aseprite.exe -b --script temp.lua
                              │  prints  @@ASEMCP@@<json>  (or @@ASEMCP_ERR@@)
                              ▼
                         runner parses the sentinel  ──>  dict back to the client

Drawing primitives (line, rectangle, ellipse, flood fill) are implemented deterministically in Lua and operate on a full-canvas copy of the target cel, so coordinates are always in sprite space and results are identical across runs. Exports use the Aseprite CLI's native flags (--sheet, --scale, --data, …).

Project layout

src/aseprite_mcp/
  app.py          FastMCP instance + usage instructions
  config.py       locate Aseprite, workspace, path resolution
  luagen.py       Python->Lua serializer + shared Lua PRELUDE + script assembly
  runner.py       run_lua() / run_cli(), parse sentinel JSON
  server.py       imports all tool modules, main()
  tools/          one module per domain: sprite, inspect, layers, frames, tags,
                  cels, drawing, brushes, effects, text, tilemap, image, palette,
                  slices, transform, export, reference (+ common.py)
docs/TOOLS.md     full auto-generated tool reference
scripts/          gen_tool_docs.py (regenerates docs/TOOLS.md)
tests/            pytest suite (auto-skips without Aseprite)

Notes & limitations

• Stateless by design. Each tool call is an independent headless Aseprite process, so transient state (the GUI selection, undo history, the "active" sprite) does not persist between calls. Operations that would need a persistent selection instead take explicit coordinates. A future live-GUI mode can layer on top of this without changing the tool API.

• Use a .aseprite/.ase extension to keep layers, frames, and tags editable. Saving to .png/.gif flattens.

• get_pixels is capped at 4096 px (e.g. 64×64) per call — read in tiles for larger areas.

• Anti-aliasing (antialias=True) only applies to RGB sprites; it's ignored on indexed/gray. Tilemaps and reference layers require Aseprite 1.3+.

Troubleshooting

• "Could not locate Aseprite." Set ASEPRITE_PATH to the full executable path.

• Nothing happens / permission denied on save. Ensure the workspace path is writable. Relative filenames go under ASEPRITE_MCP_WORKSPACE (default <repo>/workspace).

• Timeouts on big operations: raise ASEPRITE_MCP_TIMEOUT (seconds).

• A tool errors with a Lua message. The message is surfaced verbatim from Aseprite — it usually names the bad argument (e.g. a missing layer/frame).

• Tests all skip. That's expected when Aseprite isn't installed/found; set ASEPRITE_PATH to run them for real.

Development

uv run pytest                              # integration tests (need Aseprite)
uv run aseprite-mcp                        # run the server over stdio (manual debugging)
uv run python scripts/gen_tool_docs.py     # regenerate docs/TOOLS.md

See CONTRIBUTING.md for the architecture and how to add a tool, and CHANGELOG.md for release notes.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md, add a test for your change, and regenerate the tool reference before opening a PR.

License

MIT © Brendan Malloy.

Disclaimer

This is an independent, unofficial project and is not affiliated with or endorsed by Aseprite or Igara Studio S.A. "Aseprite" is a trademark of its respective owner. You need your own licensed copy of Aseprite for this server to function.