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.

• 108 tools — including high-level workflow tools that scaffold and validate whole assets in one call, and a batch op-runner that applies many edits atomically in a single Aseprite process — 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), a GUI companion view, and a health_check self-test.

• Sandboxed file access — by default the file capability is scoped to the workspace (relative paths only; absolute/.. paths rejected unless you opt in).

• No-clobber by default — output-writing tools refuse to overwrite an existing file; pass overwrite=True to replace it intentionally.

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

🟢 Easy — one call scaffolds usable pixel art

🟡 Medium — animation & tag generation

🔴 Hard — the full pipeline: create → animate → validate → export

validate_sprite_for_game_export → passed ✅  (width, height, color_mode, min_frames, required_tags)
export_game_asset_bundle        → hero.png · hero.gif · hero_sheet.png (+JSON) · hero_idle.gif · manifest.json

Related MCP server: aseprite-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 108 tools will be available. Ask the agent to run health_check to confirm Aseprite is wired up correctly.

High-level workflows

Beyond the low-level tools, a few workflow tools scaffold a whole asset in one call and return a manifest (created files, paths, frames, tags, dimensions, and suggested next steps) so an agent can keep going. They compose the low-level tools — deterministic scaffolding, no AI generation.

"Make me an idle-animated hero and a game-ready bundle."

1. create_character_sprite("hero", 32, 32, base_color="#3878c8") — layers + palette + placeholder.

2. Draw the character on the body / details layers (low-level tools).

3. make_4_frame_idle_animation("hero.aseprite") — 4-frame loop tagged idle.

4. validate_sprite_for_game_export("hero.aseprite", expected_width=32, required_tags=["idle"]) — confirm it's game-ready.

5. export_game_asset_bundle("hero.aseprite", scale=8) — PNG/GIF/sheet+JSON/manifest in hero_bundle/.

Workflow manifest contract

Every workflow tool returns a standardized workflow_manifest.v1 object (defined in core/manifest.py) so the asset layer stays consistent as it grows. Always present: ok, schema_version, kind, created_files[], suggested_next_actions[], warnings[]. Included when relevant: sprite{}, exports[], palette{}, animation{}, tilemap{}. File/export entries are {role, path, format, metadata_path?}.

{
  "ok": true,
  "schema_version": "workflow_manifest.v1",
  "kind": "character_sprite",
  "sprite": { "path": "...", "width": 32, "height": 32, "color_mode": "rgb",
              "frames": 1, "layers": ["body", "details"], "tags": [] },
  "created_files": [ { "role": "source_sprite", "path": "...", "format": "aseprite" } ],
  "palette": { "colors": ["#1b1f2a", "..."], "count": 5 },
  "suggested_next_actions": ["Draw the character on the 'body' layer", "..."],
  "warnings": []
}

Batch operations

apply_operations applies a list of edits to one sprite in a single Aseprite process, atomically — open once → run every op inside one transaction → save only if all succeed. This collapses multi-launch agent flows (add layer → draw → add frame → tag) into one fast, all-or-nothing call. Pass dry_run=true to validate the op list without launching Aseprite.

apply_operations("hero.aseprite", [
  {"op": "add_layer",      "args": {"name": "fg"}},
  {"op": "fill_layer",     "args": {"layer": "fg", "color": "#1d2b53"}},
  {"op": "draw_rectangle", "args": {"layer": "fg", "x": 2, "y": 2, "width": 12, "height": 8, "color": "#ff004d"}},
  {"op": "add_frame",      "args": {"copy_from": 1, "duration_ms": 120}},
  {"op": "add_tag",        "args": {"name": "idle", "from": 1, "to": 2}}
])

If any op fails, the whole batch rolls back and the error names the failing op index. v1 ops: layer add/rename/visible/opacity/remove · frame add/duplicate/duration · tag add/remove · draw set_pixel/line/rectangle/fill_rectangle/ellipse/fill_ellipse/fill_layer/clear_layer · slice add/remove · replace_color.

Tool catalogue

Relative filenames resolve inside the workspace (absolute paths require ASEPRITE_MCP_ALLOW_ABSOLUTE=1 — see Security). 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

Batch operations

GUI companion mode

Health & self-test

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)

Security

This server hands an AI agent a file capability, so access is scoped by default:

• Workspace-sandboxed paths. Relative filenames resolve under ASEPRITE_MCP_WORKSPACE (default <repo>/workspace). Absolute paths and paths that escape the workspace via .. (or a symlink that points outside it) are rejected unless you set ASEPRITE_MCP_ALLOW_ABSOLUTE=1.

• No-clobber by default. Output-writing tools (create_sprite, save_sprite_as, export_*, export_game_asset_bundle) refuse to overwrite an existing file; pass overwrite=True to replace it on purpose. Multi-file exports validate every target up front, so they fail before writing anything if any target already exists.

• No shell, no injection. Aseprite is invoked with list-form arguments (never a shell), and every user value is passed into generated Lua through an escaped ARG table — user input is never concatenated into Lua source.

• Bring your own Aseprite. The server only runs the Aseprite binary you point it at.

Run health_check to confirm the configuration (Aseprite path, workspace, sandbox state).

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.