aseprite-mcp

English | 中文

A TypeScript Aseprite MCP (Model Context Protocol) server.

It exposes Aseprite to LLM clients like Claude as 76 tools (drawing, layers, frames/cels, tilemaps, palettes, animation tweens, transforms, spritesheet export, ...), driving Aseprite headlessly by generating Lua scripts.

How it works

Each tool turns a high-level intent into a Lua script, then runs it with Aseprite -b --script <tmp.lua> and returns the result. The Lua is wrapped in xpcall, so runtime errors come back with a full traceback.

Requirements

• Node.js ≥ 20 (developed on Node 24)
• Aseprite (CLI-capable; Steam or standalone install both work)

Install

From npm (recommended):

npm install -g @letsagents/aseprite-mcp

After install, the aseprite-mcp command is available (see Run and the MCP client config below).

From source (development):

git clone https://github.com/letsagents/aseprite-mcp.git
cd aseprite-mcp
npm install
npm run build      # tsc -> dist/

Locating the Aseprite executable

The Aseprite binary is resolved in this priority order:

1. CLI flag --aseprite-path <PATH>
2. Environment variable ASEPRITE_PATH
3. PATH search (aseprite / aseprite.exe)
4. Common Windows install locations (Program Files, Steam, %LOCALAPPDATA%\Programs\Aseprite)
5. Error if none of the above is found

If your Aseprite is in a non-standard location (e.g. a Steam library on another drive), set it explicitly:

# Replace with the path to your Aseprite executable
export ASEPRITE_PATH="/path/to/your/Aseprite.exe"

Output paths

This server does not configure an output directory. Every filename argument must be an absolute path, provided by the caller (you, or the LLM after asking you). If the LLM doesn't know where to save, it asks you for the output location before invoking the tool. There is no --output-dir flag, no ASEPRITE_OUTPUT_DIR env var, and no default output directory.

Run

# After a global npm install:
aseprite-mcp

# From source:
npm start           # node dist/index.js
# Or during development:
npm run dev         # tsx src/index.ts (no build needed)

Connect your MCP client

Standard stdio server, supporting Claude Code / Cursor / Cline / Codex, etc. For Claude Code, .mcp.json:

{
  "mcpServers": {
    "aseprite": {
      "type": "stdio",
      // Use the bin name after a global npm install; from source use "node" + the absolute path to dist/index.js
      "command": "aseprite-mcp",
      "env": {
        // Only needed when Aseprite isn't in a standard install location; otherwise the whole env block can be omitted
        "ASEPRITE_PATH": "/path/to/your/Aseprite.exe"
      }
    }
  }
}

Other clients (Cursor .cursor/mcp.json / Codex config.toml, etc.) use the same shape, just a different file location.

Scripts

| Script | What it does | |---|---| | npm run build | Compile src/ to dist/ (excludes tests) | | npm run dev | Run directly via tsx (no build) | | npm start | Run the compiled server | | npm test | Run all unit tests (node:test, zero extra deps) | | npm run typecheck | tsc --noEmit type check |

Tests

Tests use Node's built-in node:test runner — no test framework dependency. They are pure unit tests (assertions on generated Lua strings + handler logic via a mock runner); no test requires a real Aseprite install.

npm test

Project layout

src/
├── index.ts          # entry: CLI args + Aseprite location + stdio transport
├── server.ts         # McpServer: tools + 2 resources + 1 prompt
├── context.ts        # Ctx { runner, verbose }
├── runner.ts         # LuaRunner interface + RunOutcome
├── error.ts          # AsepriteError + JSON-RPC error code mapping
├── aseprite/         # path resolution + subprocess spawn (xpcall wrapper)
├── lua/              # color parsing, Lua escaping, emit/* (per-domain Lua gen)
└── tools/            # per-domain tool registration (schema + handler)

Development guide

See AGENTS.md (cross-tool project instructions, shared by Codex / Cursor / Copilot / Gemini; architecture conventions + red lines + quick reference). The Claude Code entry is CLAUDE.md.

License

MIT