Aseprite MCP Extension

A Model Context Protocol (MCP) bridge for controlling Aseprite from AI clients such as Claude Code or Codex.

The project has two parts:

• An Aseprite extension written in Lua. It connects to a local WebSocket server and executes Aseprite API calls.
• A Node.js MCP server written in TypeScript. It exposes MCP tools and forwards requests to the Aseprite extension.

Architecture

AI client
  <-> MCP over stdio
Node.js MCP server
  <-> WebSocket ws://localhost:28474
Aseprite Lua extension
  <-> Aseprite scripting API
Aseprite editor

The MCP server is normally started by the AI client through MCP configuration. The Aseprite extension is started from Aseprite's menu and reconnects automatically if the MCP server restarts.

Requirements

• Aseprite 1.3+ with scripting enabled
• Node.js 18+
• npm

This project has been adjusted for source-built Aseprite versions where extension menu groups and WebSocket behavior can differ from packaged releases.

Install

1. Build the MCP server

cd "<path-to-aseprite-mcp-extension>\server"
npm install
npm run build

2. Import the Aseprite extension

Use the packaged extension file:

<path-to-aseprite-mcp-extension>\aseprite-mcp-bridge.aseprite-extension

In Aseprite:

1. Open Edit > Preferences > Extensions.
2. Click Add Extension.
3. Select aseprite-mcp-bridge.aseprite-extension.
4. Restart Aseprite.

After restart, the extension commands should appear under:

File > Scripts > MCP Bridge

Available menu commands:

• Start MCP Bridge
• Stop MCP Bridge
• Show Status
• Enable Debug Log
• Disable Debug Log

MCP Configuration

Add the MCP server to your AI client's MCP configuration.

Example:

{
  "mcpServers": {
    "aseprite": {
      "command": "node",
      "args": [
        "<path-to-aseprite-mcp-extension>\\server\\dist\\index.js"
      ],
      "env": {
        "MCP_WS_PORT": "28474"
      }
    }
  }
}

MCP_WS_PORT defaults to 28474. The Lua extension currently connects to ws://localhost:28474.

Usage

1. Start Aseprite.
2. Import and enable the extension if you have not already done so.
3. Select File > Scripts > MCP Bridge > Start MCP Bridge.
4. Start or restart your MCP-enabled AI client.
5. Ask the AI client to use the Aseprite tools.

You usually do not need to run node dist/index.js manually if your AI client starts MCP servers from config.

For a visible smoke test, ask the AI to:

1. Create a 64x64 RGB sprite.
2. Fill a red rectangle at x=10, y=10, width=40, height=40.

Creating a blank sprite alone can look like nothing changed because the canvas is empty.

Tools

Sprite and document tools

| Tool | Description | | --- | --- | | create_sprite | Creates a new sprite with width, height, and color mode. Also installs a default color palette so the color bar is not all black. | | get_sprite_info | Returns metadata for the active sprite. | | export_image | Exports the current sprite to an image file. |

Layer and cel tools

| Tool | Description | | --- | --- | | get_layers | Lists layers in the active sprite. | | create_layer | Creates and selects a new layer. | | get_cels | Lists cel metadata, optionally filtered by layer or frame. | | copy_cel | Copies a cel from one frame to another on a layer. | | move_cel | Moves a cel from one frame to another on a layer. | | clear_cel | Clears a cel on a layer/frame. |

Drawing tools

| Tool | Description | | --- | --- | | draw_pixels | Draws individual pixels. | | fill_rect | Fills a rectangle with a solid color. | | draw_line | Draws a line using integer pixel coordinates. | | fill_color | Flood-fills a region from a seed point. | | get_pixel | Reads one pixel color. |

Drawing tools accept optional layerName, layerIndex, and frame parameters where applicable.

Frame and animation tools

| Tool | Description | | --- | --- | | add_frame | Adds a frame at the end. | | insert_frame | Inserts a frame at a specific 0-based index. | | duplicate_frame | Duplicates an existing frame. | | delete_frame | Deletes a frame. | | set_active_frame | Selects the active frame. | | set_frame_duration | Sets one frame duration in milliseconds. | | set_frame_durations | Sets several frame durations at once. | | get_frame_durations | Reads all frame durations. |

Animation tag and export tools

| Tool | Description | | --- | --- | | get_tags | Lists animation tags. | | create_tag | Creates an animation tag over an inclusive frame range. | | update_tag | Updates tag name, playback direction, repeats, color, or data. | | delete_tag | Deletes a tag by name. | | export_spritesheet | Exports a sprite sheet image and optional JSON data. |

Supported tag directions:

• forward
• reverse
• pingpong
• pingpong_reverse

Example MCP Tool Calls

Create a sprite:

{
  "width": 128,
  "height": 128,
  "colorMode": "RGB"
}

Draw on frame 0:

{
  "x": 10,
  "y": 10,
  "width": 40,
  "height": 40,
  "color": { "r": 255, "g": 0, "b": 0, "a": 255 },
  "frame": 0
}

Create a simple animation tag:

{
  "name": "walk",
  "fromFrame": 0,
  "toFrame": 5,
  "aniDir": "pingpong",
  "repeats": 0
}

Set frame durations:

{
  "durations": [
    { "frame": 0, "duration": 100 },
    { "frame": 1, "duration": 100 },
    { "frame": 2, "duration": 120 }
  ]
}

Export a sprite sheet:

{
  "textureFilename": "C:\\Users\\admin\\Desktop\\walk.png",
  "dataFilename": "C:\\Users\\admin\\Desktop\\walk.json",
  "type": "packed",
  "dataFormat": "json_hash",
  "tag": "walk",
  "trim": true,
  "ignoreEmpty": true
}

Reconnect Behavior

The extension is designed to stay running while the MCP server restarts.

• It reconnects to ws://localhost:28474.
• Reconnect wait is 3 seconds.
• A heartbeat ping runs every 5 seconds.
• Stop MCP Bridge stops the socket, reconnect timer, and heartbeat timer.
• Show Status displays whether the extension is stopped, connecting, reconnecting, or connected.

If the MCP server is off, the extension can remain running and reconnect after the server starts again.

Debugging

Use:

File > Scripts > MCP Bridge > Enable Debug Log

This enables console logs such as:

• connection state
• received method name
• raw WebSocket message if JSON parsing fails
• response sent back to the MCP server

Disable it after debugging:

File > Scripts > MCP Bridge > Disable Debug Log

Debug logging is disabled by default so Aseprite's console does not pop up for every tool call.

Troubleshooting

File > Scripts > MCP Bridge does not appear

Remove and re-import the latest .aseprite-extension, then restart Aseprite.

Make sure the packaged archive contains package.json at the archive root, not inside a parent folder. The current packaged file should contain:

package.json
scripts/mcp_bridge.lua

EADDRINUSE: address already in use :::28474

Another MCP server is already using port 28474.

On Windows:

netstat -ano | findstr :28474
tasklist /FI "PID eq <PID>"
taskkill /PID <PID> /F

If your AI client manages the MCP server, do not also run node dist/index.js manually.

AI calls tools but Aseprite does not visibly change

Check these points:

• Start MCP Bridge was run in Aseprite.
• The MCP server is running and connected.
• Use Show Status.
• Enable debug log and confirm Received method: appears.
• Blank sprite creation alone is not visually obvious. Test with fill_rect.

JSON decode errors

The extension includes compatibility handling for source-built Aseprite WebSocket behavior:

• WebSocket compression is disabled.
• Server sends text frames.
• Lua trims/normalizes the JSON envelope before decoding.

If errors continue, enable debug log and inspect the Raw WebSocket message line.

RGB sprite palette is all black

create_sprite now applies a default 256-color palette after creating the sprite. Re-import the latest extension if you still see an all-black color bar.

Development

Build server:

cd server
npm run build

Package extension:

cd "<path-to-aseprite-mcp-extension>"
Compress-Archive -Path .\extension\package.json, .\extension\scripts -DestinationPath .\aseprite-mcp-bridge.zip -Force
Move-Item .\aseprite-mcp-bridge.zip .\aseprite-mcp-bridge.aseprite-extension -Force

After changing Lua extension code, re-import the .aseprite-extension in Aseprite and restart Aseprite.

After changing TypeScript server code, run npm run build and restart the MCP client/server.

Docs and Skills

The repository also includes optional supporting material:

• docs/demo/ contains demo videos for image and animation workflows.
• skills/pixel-art/ contains a Codex/agent skill with pixel-art guidance.
• skills/pixel-art-sprites/ contains a Codex/agent skill focused on sprite creation and animation.

The skills/ folders are not required for the Aseprite extension or MCP server to run. They are included to help AI agents produce better pixel-art prompts and Aseprite workflows when this repository is used as context.

Project Structure

aseprite-mcp-extension/
|-- aseprite-mcp-bridge.aseprite-extension
|-- docs/
|   `-- demo/
|       |-- aseprite_extension_animation.mp4
|       `-- aseprite_extension_image.mp4
|-- extension/
|   |-- package.json
|   |-- aseprite-extension.toml
|   `-- scripts/
|       `-- mcp_bridge.lua
|-- server/
|   |-- package.json
|   |-- tsconfig.json
|   |-- src/
|   |   |-- index.ts
|   |   |-- transport.ts
|   |   |-- config.ts
|   |   |-- types.ts
|   |   `-- tools/
|   `-- dist/
`-- skills/
    |-- pixel-art/
    |   |-- SKILL.md
    |   `-- references/
    `-- pixel-art-sprites/
        |-- SKILL.md
        `-- references/