Aseprite MCP

An MCP server that drives Aseprite — create sprites, draw with a text-grid interface, manage layers/frames/tags, import and quantize reference images, and export — all as tool calls an LLM can make, with a rendered preview after every mutation so the model sees what it drew.

Requires your own licensed copy of Aseprite ≥1.3 — not included or bundled. See Licensing.

Supported Aseprite versions: 1.3.0–1.3.x tested (developed against 1.3.18.1-dev); 1.4-beta best-effort. The Lua scripting API drifts between versions — if a tool call fails on your build with an error naming a Lua field or method, that's the most likely cause.

60-second quickstart

uv tool install aseprite-mcp   # or: uvx aseprite-mcp
aseprite-mcp --doctor          # confirms Aseprite is found and the bridge works

Add to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "aseprite": {
      "command": "uvx",
      "args": ["aseprite-mcp"],
      "env": {
        "ASEPRITE_PATH": "/Applications/Aseprite.app/Contents/MacOS/aseprite",
        "ASEPRITE_MCP_WORKSPACE": "~/pixel-art"
      }
    }
  }
}

ASEPRITE_PATH is optional — the server searches common install locations first (see discovery.py) and only needs it if your install is somewhere unusual. ASEPRITE_MCP_WORKSPACE defaults to ~/.aseprite-mcp/workspace; every sprite path a tool call uses is relative to it (a jailed directory, not an arbitrary filesystem path).

Then, from your MCP client: "Create a 32x32 knight sprite using the PICO-8 palette." The sprite-character prompt (below) walks the model through a silhouette-first workflow that produces noticeably better results than an unguided request.

Related MCP server: Aseprite MCP Tools

Tools

Every mutating tool returns a rendered preview alongside its text result — the model sees the consequence of each action without a separate "show me" step.

Prompts

sprite-character, sprite-tileset, animate-walkcycle, from-reference, palette-explore — each a concrete, checkpointed tool-call sequence rather than open-ended instructions. Invoke as a slash command or prompt template in your MCP client.

Resources

aseprite://guide/pixel-art (the craft rules — silhouettes, hue-shifted ramps, avoiding pillow shading), aseprite://guide/lua-api (condensed Lua reference for run_lua, including the gotchas this project found the hard way), aseprite://palettes (bundled preset colors).

Troubleshooting

"Could not find Aseprite" — set ASEPRITE_PATH explicitly to the executable (not the .app bundle on macOS — the binary inside it, e.g. /Applications/Aseprite.app/Contents/MacOS/aseprite). Run aseprite-mcp --doctor to see exactly which paths were tried.

A tool call times out — the default per-command timeout is 10s (30s for exports), generous for normal use (measured average is under 100ms). A timeout usually means Aseprite itself hung on something unrelated to the command — check for a stray Aseprite process and kill it, then retry.

A tool call fails naming a Lua field/method that "should" exist — likely version drift; the Lua scripting API isn't perfectly stable across Aseprite releases. Check your Aseprite version against the supported range above, and see the pitfall table in aseprite-mcp-build-flow.md for known version-sensitive spots.

Development

uv sync                          # installs deps + dev tools (mypy, pytest)
uv run mypy src                  # required clean before every commit
ASEPRITE_PATH=... uv run pytest tests/   # integration tests need a real binary;
                                          # skip cleanly without one

CLAUDE.md has the full rule set this project is built against. aseprite-mcp-build-flow.md is the build log — architecture, milestone-by-milestone findings, and every Aseprite/SDK gotcha discovered while building this, verified against the real binary rather than assumed from docs.

License

MIT for this project's own code. Aseprite itself is not included — see the licensing note at the top of this file.