Skip to main content
Glama

Let an AI assistant draw live in your running Aseprite via the Model Context Protocol.

Unofficial community project. Not affiliated with or endorsed by Anthropic or Igara Studio (Aseprite). Use at your own risk – see DISCLAIMER.md.

MCP client ⇄ stdio ⇄ aseprite-mcp ⇄ WebSocket 127.0.0.1 ⇄ Aseprite + MCP Bridge extension

The assistant can create sprites, set exact pixels, use Aseprite's tools (line, rectangle, ellipse, bucket, curve, freehand …), manage layers and animation frames, undo/redo, and look at its own result as an upscaled PNG to iterate on it. Every change lands in Aseprite's undo history.

Drawing is designed to be cheap in tokens: whole sprites are sent as a palette plus text rows, several steps fit into one call, and pixels can be read back in the same text format.

Requirements

  • Aseprite v1.3 or later (Windows, macOS or Linux; the Steam version works too)

  • Node.js 20+ (some Linux distributions ship older versions – use nodejs.org or a version manager)

  • An MCP client that runs local (stdio) servers, e.g. Claude Code, Claude Desktop, Cursor, VS Code (GitHub Copilot), Windsurf, Gemini CLI or Codex CLI. Clients that only support remote (HTTP) servers, such as ChatGPT, cannot use it.

Related MCP server: aseprite_mcp

Installation

1. Server

git clone https://github.com/sloplink/aseprite-mcp
cd aseprite-mcp
npm install

2. Aseprite extension

Download aseprite-mcp-bridge.aseprite-extension from the releases (or build it with npm run build), then in Aseprite: Edit › Preferences › Extensions › Add Extension.

The extension only needs an update when a release says so – many releases change just the server. aseprite_status shows both versions and warns if the installed extension is too old. After updating the extension, restart Aseprite (otherwise the old extension code keeps running).

3. Pairing token

Server and extension authenticate each other with a shared secret. Print it with:

node server.mjs token

In Aseprite open File › MCP Bridge… and paste the token into the Token field. It is remembered between sessions. node server.mjs token --new rotates it.

4. Register the server with your MCP client

Claude Code:

claude mcp add --scope user aseprite -- node /absolute/path/to/aseprite-mcp/server.mjs

Claude Desktop, Cursor, Windsurf, Gemini CLI, Cline and most other clients use this JSON (claude_desktop_config.json, ~/.cursor/mcp.json, ~/.codeium/windsurf/mcp_config.json, ~/.gemini/settings.json, …):

{
  "mcpServers": {
    "aseprite": {
      "command": "node",
      "args": ["/absolute/path/to/aseprite-mcp/server.mjs"]
    }
  }
}

VS Code (.vscode/mcp.json):

{
  "servers": {
    "aseprite": { "type": "stdio", "command": "node", "args": ["/absolute/path/to/aseprite-mcp/server.mjs"] }
  }
}

Codex CLI (~/.codex/config.toml):

[mcp_servers.aseprite]
command = "node"
args = ["/absolute/path/to/aseprite-mcp/server.mjs"]

On Windows write the path as C:/Users/you/aseprite-mcp/server.mjs (or with \\ in JSON).

Notes for other assistants: the server sends a usage guide as MCP instructions; if your client ignores them, ask the assistant to call aseprite_help first. If your client cannot show images from tools, the assistant can still check its work with aseprite_read_pixels.

Usage

  1. Start your MCP client (this starts the server).

  2. In Aseprite open File › MCP Bridge… and press Connect. Keep the window open; it shows Connected ✓ once both sides have verified the token.

  3. Ask, for example: “Create a 32×32 sprite and draw a pixel-art mushroom. Look at the result and improve it.”

The order of steps 1 and 2 does not matter; the bridge reconnects automatically.

Tools

Tool

Purpose

aseprite_status

Connection and sprite info (size, layers, frames)

aseprite_help

The usage guide, for clients that ignore server instructions

aseprite_new_sprite, aseprite_open, aseprite_save

Create, open, save or export

aseprite_pixel_map

Draw exact pixels from a palette + text rows – the cheapest way to draw (~10× less input than set_pixels)

aseprite_set_pixels

Set a few exact pixels (one undo step)

aseprite_draw

Use a tool: pencil, line, rectangle, ellipse, paint_bucket, curve, polygon …

aseprite_clear

Clear a layer or a rectangle

aseprite_layer, aseprite_frame

Layers and animation frames

aseprite_history

Undo / redo

aseprite_batch

Run several operations in one call

aseprite_read_pixels

Read pixels back as palette + text rows (same format as pixel_map)

aseprite_copy

Copy or mirror a region to another position, layer or frame

aseprite_animation

Draw several frames in one call (creates missing frames, frames can be deltas)

aseprite_palette

Save, list and delete named palettes, collect one from the image, or build hue-shifted shading ramps; use via paletteName

aseprite_outline

Selective outline ("sel-out") or solid outline around/inside the shapes

aseprite_sprites

Lists the open sprites and switches between them

aseprite_backups

Lists the automatic backup copies (open one with aseprite_open to restore it)

aseprite_selection

The region the artist selected; most tools also take rect: "selection"

aseprite_changes

Watch mode: only the pixels the artist changed since the last call

aseprite_view

Returns an upscaled PNG so the assistant can see the image (optionally only a zoomed-in rect); critique: true gives one small review sheet (colour, grayscale, silhouette, 1x, colour-blindness)

aseprite_run_lua

Arbitrary Lua – off by default, see below

Most tools work with the MCP Bridge extension 0.4.0 or newer; aseprite_selection, aseprite_changes and rect: "selection" need 0.6.0, aseprite_sprites and the sprite guard need 0.7.0. The server tells you when an update is needed.

Sprite guard: the tools remember which sprite they work on (the one the assistant created or opened, or the active one after aseprite_status). If you switch to another tab while the assistant works, its next call stops with a message instead of drawing into the wrong sprite.

Automatic backups: a few seconds after the assistant changes a sprite, a copy is saved as .aseprite (all layers and frames), the newest 5 per sprite. Your own files are never overwritten, and the sprite keeps its file name and unsaved state – so unsaved work survives closing Aseprite by mistake. To restore one, press Backups… in the MCP Bridge window and pick it (or ask the assistant). The copies live in ~/.config/aseprite-mcp/autosave/<file name>/<date time>.aseprite (unsaved sprites: unsaved <date> <id>); copies older than 14 days are deleted, and all copies together stay below 200 MB. Needs extension 0.7.0.

Once connected, the MCP Bridge window shrinks to the status and a few buttons; Settings… shows token, port and the Lua option again.

The server also sends a short usage guide (instructions.md) to the MCP client, so the assistant knows the efficient workflow (pixel map → batch → view once → fix rows) up front.

Example pixel map:

{ "palette": { "k": "#1a1c2c", "r": "#b13e53", "w": "#f4f4f4" },
  "rows": ["..kk..", ".krrk.", "krwrrk", ".krrk.", "..kk.."], "x": 4, "y": 4 }

. and space leave a pixel unchanged; map a key to #00000000 to erase.

Parts that repeat can be defined once as stamps and drawn several times with place (optionally flipped) – in one image or across the frames of aseprite_animation:

{ "palette": { "k": "#1a1c2c", "w": "#f4f4f4" },
  "stamps": { "eye": { "rows": ["kw", "kk"] } },
  "place": [["eye", 5, 4], ["eye", 9, 4, "h"]] }

For art generated by a script, pixel_map and animation also accept file: the absolute path of a .json file with the same data. The rows then don't have to go through the conversation at all. The server only reads .json files and never includes their contents in error messages.

Security

  • The server listens on 127.0.0.1 only.

  • Both sides prove knowledge of the token with an HMAC-SHA256 challenge-response on every connection. Unauthenticated clients are dropped, and the extension ignores all commands from a server that fails the check. The token itself is never sent over the socket.

  • The token file is created with mode 600 in ~/.config/aseprite-mcp/token (or $XDG_CONFIG_HOME).

  • aseprite_run_lua needs two opt-ins: the server must be started with ASEPRITE_MCP_ALLOW_LUA=1, and Allow arbitrary Lua code must be ticked in the MCP Bridge window. Only enable it if you trust what your assistant is doing.

  • aseprite_open / aseprite_save can read and write any path your user can access, but only files with an image format Aseprite supports (.aseprite, .png, .gif, …) and absolute paths.

  • The file option of aseprite_pixel_map / aseprite_animation only reads .json files that belong to you and lie in the system temp directory or /tmp (or in ASEPRITE_MCP_FILE_DIRS); symlinks are resolved first, and error messages never contain the file's contents.

  • Aseprite stores the token in the extension's preferences (~/.config/aseprite/extensions/aseprite-mcp-bridge/__pref.lua), which is readable by other users of the computer by default. On a shared computer run chmod 700 ~/.config/aseprite.

  • aseprite_palette stores palettes in ~/.config/aseprite-mcp/palettes.json.

Configuration

Variable

Default

Meaning

ASEPRITE_MCP_PORT

9123

WebSocket port (also set it in the MCP Bridge window)

ASEPRITE_MCP_ALLOW_LUA

unset

1 registers aseprite_run_lua

ASEPRITE_MCP_TIMEOUT

15000

Per-command timeout in ms

ASEPRITE_MCP_TOKEN

–

Use this token instead of the token file

ASEPRITE_MCP_TOKEN_FILE

see above

Token file location

ASEPRITE_MCP_PALETTE_FILE

~/.config/aseprite-mcp/palettes.json

Where aseprite_palette stores palettes

ASEPRITE_MCP_AUTOSAVE

~/.config/aseprite-mcp/autosave

Folder for automatic backup copies, or off

ASEPRITE_MCP_AUTOSAVE_KEEP

5

Backup copies kept per sprite

ASEPRITE_MCP_AUTOSAVE_DAYS

14

Backup copies older than this are deleted

ASEPRITE_MCP_AUTOSAVE_MB

200

All backup copies together stay below this size

ASEPRITE_MCP_FILE_DIRS

system temp directory (+ /tmp on macOS/Linux)

Directories the file option may read from (separated by :, on Windows ;)

Example with Claude Code:

claude mcp add --scope user --env ASEPRITE_MCP_ALLOW_LUA=1 aseprite -- node /absolute/path/to/aseprite-mcp/server.mjs

Troubleshooting

  • “Aseprite is not connected” – Is the MCP Bridge window open and showing Connected ✓?

  • “Token rejected” – Run node server.mjs token and paste the value again.

  • Stuck on “Waiting for server” – Is your MCP client running? In Claude Code, /mcp shows the server status.

  • Two MCP client sessions at once – only the first one gets the port.

  • “extension is outdated” / version warning in aseprite_status – install the extension from the same release as the server and restart Aseprite.

  • New tools missing in the assistant – restart the MCP client (Claude Code: /mcp → reconnect).

  • Aseprite may ask for permission the first time the extension opens a network connection; allow it.

  • Aseprite in a sandbox (e.g. Flatpak Steam) – it has its own /tmp. Images up to 128×128 px are sent directly and work anyway; for larger aseprite_view calls pass a smaller rect. open/save paths must be visible inside the sandbox.

  • The assistant draws badly or wastes tokens – make sure it read the usage guide (aseprite_help).

Development

npm test         # all tests
npm run build    # creates dist/aseprite-mcp-bridge.aseprite-extension

The test suite has three parts:

File

What it checks

Needs

test/e2e.test.mjs

real server ⇄ real plugin.lua in a mocked Aseprite; server tools against a fake Aseprite

lua5.4 (or 5.3) + dkjson (Debian/Ubuntu: lua-dkjson, otherwise luarocks install dkjson) for the plugin part

test/aseprite.test.mjs

every extension handler inside a real Aseprite in batch mode (aseprite -b)

Aseprite; found automatically (PATH, Steam, /Applications) or via ASEPRITE=/path/to/aseprite

test/versions.test.mjs

server, npm package and CHANGELOG carry the same version; the extension's version fits the server (MIN_EXTENSION)

–

Parts whose requirements are missing are skipped. CI runs everything except the real-Aseprite test on Node 20–24 (Linux) and on macOS and Windows.

Releasing

  1. Bump the version in package.json, package-lock.json (npm install --package-lock-only) and server.mjs (VERSION), and add a CHANGELOG.md section.

  2. Only if the extension changed: set its new version in extension/package.json and EXTENSION_VERSION (extension/handlers.lua). If the server now relies on a new or changed extension command, also raise MIN_EXTENSION (server.mjs) to that version – older installed extensions then get a warning. Say in the CHANGELOG whether users need to update the extension.

  3. Run npm test locally with Aseprite installed – it fails if these numbers don't fit together.

  4. Push a tag vX.Y.Z; the release workflow attaches the built extension to a GitHub release.

License

MIT – see LICENSE. Written with the help of Claude.

Available Tools

23 tools
aseprite_animationDraw an animationA

Draws several frames in ONE call, each as a pixel map, creating missing frames automatically. With copyPrevious (default) a new frame starts as a copy of the previous one, so each entry only needs the changed rows (use x/y and '.' to leave pixels unchanged; '.' never erases, map a key to '#00000000' for that). Parts that repeat across frames (head, body …) belong in stamps, placed per frame with place: [name, x, y]. For generated animations write frames/palette/stamps to a .json file and pass file. Returns the sprite status.

Inputs: file, layer, start, frames, +5 more.

aseprite_backupsBackup copiesA
Read-only

Lists the automatic backup copies (newest first). A few seconds after the assistant changes a sprite, a copy is saved as .aseprite; the artist's own files are never overwritten. Open one with aseprite_open to restore it.

Inputs: limit.

aseprite_batchBatch operationsA

Runs several operations in ONE call, in order (saves round trips and tokens). Each item is {"op": , ...the same arguments as the tool aseprite_}. Allowed ops: new_sprite, pixel_map, set_pixels, draw, clear, layer, frame, copy, animation, outline, history, save. Stops at the first error; earlier ops stay applied (each op is its own undo step). Returns one short result per op plus the final sprite status if layers/frames changed. Example: [{"op":"layer","action":"new","name":"bg"},{"op":"draw","tool":"filled_rectangle","points":[[0,0],[15,15]],"color":"#5fcde4"},{"op":"layer","action":"new","name":"fg"},{"op":"pixel_map","palette":{"k":"#000"},"rows":["kk"],"x":4,"y":4}]

Inputs: ops (required).

aseprite_changesWhat the artist changedA
Read-only

Watch mode for drawing together. The first call starts watching the active sprite. Later calls return only the pixels the ARTIST changed since the previous call (your own tool calls are not reported), as a pixel map of the changed region: '.' = unchanged, '-' = erased, other keys = new colours. Feed it to aseprite_pixel_map to build on it. peek=true looks without moving the baseline; reset=true starts over.

Inputs: peek, frame, reset, palette, +1 more.

aseprite_clearClearB

Clears the whole layer in the frame, or only a rectangle.

Inputs: rect, frame, layer.

aseprite_copyCopy / mirror a regionA

Copies a rectangle of pixels, optionally flipped, to another position, layer or frame (one undo step). Without x/y it writes back in place, so flip='h' mirrors the region where it is. Symmetry example on a 16px-wide sprite: rect [0,0,8,16], flip 'h', x 8 mirrors the left half onto the right half.

Inputs: rect (required), x, y, flip, +5 more.

aseprite_drawDraw with a toolA

Uses an Aseprite tool like a mouse stroke. line/rectangle/filled_rectangle/ellipse/filled_ellipse take 2 points (start, end; inclusive). pencil/eraser/spray take any number of points (freehand path). paint_bucket takes 1 point. curve takes 4 points. polygon/contour take the corner points.

Inputs: tool (required), points (required), size, color, +7 more.

aseprite_frameManage framesA

Animation: create a frame after the given/active one (new, copies it by default, becomes active), activate (select), delete, or set its duration (in seconds). To draw several frames at once use aseprite_animation. Returns the sprite status.

Inputs: action (required), copy, frame, duration.

aseprite_helpUsage guideA
Read-only

Returns the short usage guide (efficient workflow, pixel_map format, stamps, pixel-art tips). Read it once before drawing if your client did not show the server instructions.

Inputs: no named parameters.

aseprite_historyUndo / redoC

Undoes or redoes steps.

Inputs: action (required), steps.

aseprite_layerManage layersB

Create (new, becomes active), activate (select), delete, rename, or show/hide (visible) a layer. Returns the sprite status.

Inputs: name (required), action (required), newName, visible.

aseprite_new_spriteNew spriteB

Creates a new sprite and makes it active. Returns the sprite status.

Inputs: width (required), height (required), colorMode, background.

aseprite_openOpen fileA

Opens a file (.aseprite, .png, .gif, ...) as the active sprite.

Inputs: path (required).

aseprite_outlineOutlineA

Adds a 1px outline around (outside) or on the edge of (inside) everything opaque on a layer, in one undo step. style 'selout' (default) derives each outline pixel from the colour it borders: darker and cooler on the shadow side, lighter on the side facing the top-left light – the classic selective outline. style 'solid' uses one colour. Works on sprites up to 128x128 (or pass rect). Semi-transparent pixels (alpha < 128) count as empty.

Inputs: rect, color, frame, layer, +3 more.

aseprite_paletteSaved palettesA

Stores named palettes (character -> color) on disk so they can be reused across sprites and sessions via paletteName in aseprite_pixel_map, aseprite_read_pixels, aseprite_animation. Actions: save (name + colors), list (all saved palettes), delete (name), from_image (name; collects the colors of the visible frame, or of layer/rect, and saves them with generated keys), ramp (builds hue-shifted shading ramps – cool, saturated shadows and warm highlights – from base colours; e.g. ramps [{"base":"#d63a3a","keys":"DmrRH"}] gives 5 keys dark->light with the base in the middle; saved when name is given).

Inputs: action (required), name, rect, frame, +3 more.

aseprite_pixel_mapDraw pixel mapA

Most token-efficient way to draw many exact pixels: a palette of single-character keys and one text row per pixel row. '.' and space leave the pixel unchanged; map a key to '#00000000' to erase. One undo step. Example: palette {"k":"#222034","y":"#fbf236"}, rows ["..kk..", ".kyyk.", "kyyyyk"]. Repeated parts: define stamps once and draw them with place. Generated art: write the data to a .json file and pass file.

Inputs: x, y, file, rows, +6 more.

aseprite_read_pixelsRead pixels as textA
Read-only

Reads pixels back in the same palette + rows format as aseprite_pixel_map, so you can inspect exact colors or copy/modify a region cheaply. '.' = fully transparent; trailing '.' are cut off. Without layer the visible, flattened frame is read; with layer only that layer. Pass the palette (or paletteName) you drew with to get the same keys back. Max 16384 pixels per call.

Inputs: rect, frame, layer, palette, +1 more.

aseprite_saveSaveA

Saves the active sprite. Without path the existing file is overwritten. With copy=true only a copy is exported (e.g. as .png).

Inputs: copy, path.

aseprite_selectionArtist's selectionA
Read-only

Returns the region the artist has selected in Aseprite ({empty:true} if nothing is selected), so a request like 'improve this part' needs no coordinates. Most tools also accept rect "selection" directly. mask=true adds the exact shape as rows ('#' selected) when it is not a plain rectangle.

Inputs: mask.

aseprite_set_pixelsSet pixelsA

Sets individual pixels exactly, as a single undo step. The color '#00000000' erases a pixel. For more than a few pixels prefer aseprite_pixel_map (far fewer tokens).

Inputs: pixels (required), frame, layer.

aseprite_spritesOpen spritesA

Lists the sprites open in Aseprite (id, name, size, frames, which one is active). select (id or name) switches Aseprite to that sprite and makes it the one all following tools work on – use it after an 'artist switched sprites' error or to work on several sprites in turn.

Inputs: select.

aseprite_statusStatus / sprite infoA
Read-only

Checks the connection and returns info about the active sprite: size, color mode, layers, frames, active layer/frame. Coordinates start at (0,0) in the top-left corner. The active sprite becomes the one all following tools work on.

Inputs: no named parameters.

aseprite_viewView imageA
Read-only

Renders the visible, flattened frame as an upscaled PNG so you can look at and check the result yourself. Transparency is shown as a checkerboard. Use rect to zoom into a detail. Call it once after a drawing pass, not after every step. If your client cannot show images, use aseprite_read_pixels instead. critique=true instead returns ONE small sheet for self-review: colour, grayscale (value/contrast check), black silhouette (readability) and true 1x size; add 'deutan' to panels for a colour-blindness check. Max 128x128 px (or pass rect).

Inputs: grid, rect, frame, scale, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 23 tools

    Disambiguation5/5

    Each tool targets a distinct task: pixel_map/set_pixels/draw are clearly separated by bulk vs. individual vs. shape drawing, status/sprites by active vs. all sprites, and view/read_pixels by rendered image vs. pixel data. The descriptions explicitly note when to prefer one tool over another, so an agent is unlikely to select the wrong one.

    Naming Consistency4/5

    All tools share the aseprite_ prefix and lowercase snake_case, which is predictable and consistent. However, the suffix style mixes verb commands like draw, clear, copy, and view with noun commands like layer, frame, history, palette, and changes, rather than following a strict verb_noun pattern throughout.

    Tool Count3/5

    At 23 tools, the server sits in the 16-25 range that feels heavy for a single MCP server. That said, Aseprite is a broad pixel-art editor domain and nearly every tool has a distinct purpose, so the count is defensible though not tightly scoped.

    Completeness4/5

    Core pixel-art workflows are well covered: file open/new/save, drawing and reading pixels, layer and frame management, animation, palettes, undo/redo, and even collaborative change monitoring. Obvious gaps like canvas resize, layer reordering/opacity, or frame reordering are missing but can generally be worked around with copy and new operations.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers