How to use AI in Aseprite with SpriteRelay

Before you start

• Aseprite, licensed and installed by you. CLI: Aseprite 1.3.18.1 with Lua API 40 (current CLI baseline). Live: Aseprite 1.3-rc5 or newer with Lua API 25 or newer.
• Node.js 18 or newer.
• An AI client that runs local stdio MCP servers, such as Claude Code, Claude Desktop, Codex, Cursor or VS Code with Copilot.
• The files from your purchase: spriterelay-cli-2.0.0.tgz, spriterelay-live-2.0.0.tgz and the .aseprite-extension Bridge, depending on your edition.

SpriteRelay is supplied as a .tgz package. There is no public npm package, so never install a similarly named package from the registry.

1. Install SpriteRelay CLI

Install the supplied tarball globally:

npm install -g "/absolute/path/to/spriterelay-cli-2.0.0.tgz"

Then find the installed package and your Node executable. Clients launch most reliably with absolute paths.

# PowerShell
npm root -g
(Get-Command node).Source

# Bash or zsh
npm root -g
command -v node

The launch values are your Node path plus <npm root>/spriterelay-cli/dist/index.js.

2. Register it with your AI client

Claude Code

claude mcp add --transport stdio --scope user spriterelay -- /absolute/path/to/node /absolute/path/to/spriterelay-cli/dist/index.js

If Aseprite is not found automatically, add --env ASEPRITE_PATH=/absolute/path/to/aseprite before --transport.

Codex (CLI, IDE extension and ChatGPT desktop app)

codex mcp add spriterelay -- /absolute/path/to/node /absolute/path/to/spriterelay-cli/dist/index.js

Claude Desktop, Cursor and other JSON-configured clients

Merge this entry into the client's mcpServers object (Claude Desktop: Settings › Developer › Edit Config; Cursor: .cursor/mcp.json). On Windows, double every backslash.

{
  "mcpServers": {
    "spriterelay": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/spriterelay-cli/dist/index.js"],
      "env": { "ASEPRITE_PATH": "/absolute/path/to/aseprite" }
    }
  }
}

VS Code uses a servers key with "type": "stdio"; Windsurf, Cline, Zed, Continue, Gemini CLI and JetBrains AI Assistant have their own formats. The included INSTALL.md has each one.

3. Verify CLI

1. Restart or reconnect your client and confirm spriterelay is connected.
2. Confirm exactly six tools: aseprite_doctor, sprite_inspect, sprite_patch, sprite_export, sprite_preview and file_commit.
3. Ask: “Run spriterelay's aseprite_doctor with level quick and report discovery, Aseprite version, API version, and unsupported capabilities.”

4. Install SpriteRelay Live

Live has two pieces from the same release: the MCP server and the Aseprite extension (the Bridge). Install matched versions.

npm install -g ./spriterelay-live-2.0.0.tgz

Then install the Bridge: double-click spriterelay-live-bridge-2.0.0.aseprite-extension, or in Aseprite use Edit › Preferences › Extensions › Add Extension. Register the server with your client the same way as CLI, using spriterelay-live as the command:

claude mcp add spriterelay-live -- spriterelay-live

5. Pair Live with Aseprite

1. Start your client and ask it to run live_doctor. It prints a port and a pairing token.
2. In Aseprite, run SpriteRelay Live: Pair… and paste the token. live_doctor now shows CONNECTED.
3. On first use Aseprite asks twice: once to open a localhost connection and once to write preview files. These are Aseprite's own prompts. Grant trust only to the extension from your verified SpriteRelay release.

The Bridge adds an Allow Remote Edits switch, so you can pause the assistant at any time. Uninstalling the extension is the off switch.

6. Make a first edit

Ask your assistant for something small, then review it before keeping it:

“Draw a small purple potion on a 32×32 canvas and show me a preview.”

• With Live, the change appears in the open document as one undo step. Keep it or press undo.
• With CLI, the work happens in a staged copy. Nothing reaches your project until you ask for file_commit.

Troubleshooting

Still stuck? Email support@spriterelay.com with your client, operating system and the doctor's output.