aseprite-mcp
An MCP server that lets an AI assistant control a running Aseprite instance to create and edit pixel art interactively.
Create, open, save/export sprites, and list/switch between open sprites.
Draw exact pixels via token-efficient pixel maps, set individual pixels, or use Aseprite tools (pencil, line, rectangle, ellipse, paint bucket, curve, polygon, gradient, etc.).
Manage layers and animation frames, including copy/mirror regions and drawing whole animations in one call.
Read pixels back as palette + text rows, watch artist changes, and query the artist's selection.
Render upscaled PNG previews and critique sheets so the assistant can inspect its own work.
Undo/redo, batch multiple operations, add outlines, manage saved palettes, and build shading ramps.
List and restore automatic backups.
Optionally run arbitrary Lua scripts when explicitly enabled.
Allows AI assistants to create and edit Aseprite sprites live, including setting pixels, using drawing tools, managing layers and animation frames, undo/redo, and viewing the current image as an upscaled PNG.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@aseprite-mcp Create a 32×32 sprite and draw a pixel-art mushroom. Look at the result and improve it."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 extensionThe 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 install2. 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 tokenIn 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.mjsClaude 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
Start your MCP client (this starts the server).
In Aseprite open File › MCP Bridge… and press Connect. Keep the window open; it shows Connected ✓ once both sides have verified the token.
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 |
| Connection and sprite info (size, layers, frames) |
| The usage guide, for clients that ignore server instructions |
| Create, open, save or export |
| Draw exact pixels from a palette + text rows – the cheapest way to draw (~10× less input than |
| Set a few exact pixels (one undo step) |
| Use a tool: pencil, line, rectangle, ellipse, paint_bucket, curve, polygon … |
| Clear a layer or a rectangle |
| Layers and animation frames |
| Undo / redo |
| Run several operations in one call |
| Read pixels back as palette + text rows (same format as |
| Copy or mirror a region to another position, layer or frame |
| Draw several frames in one call (creates missing frames, frames can be deltas) |
| Save, list and delete named palettes, collect one from the image, or build hue-shifted shading ramps; use via |
| Selective outline ("sel-out") or solid outline around/inside the shapes |
| Lists the open sprites and switches between them |
| Lists the automatic backup copies (open one with |
| The region the artist selected; most tools also take |
| Watch mode: only the pixels the artist changed since the last call |
| Returns an upscaled PNG so the assistant can see the image (optionally only a zoomed-in |
| 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.1only.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
600in~/.config/aseprite-mcp/token(or$XDG_CONFIG_HOME).aseprite_run_luaneeds two opt-ins: the server must be started withASEPRITE_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_savecan 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
fileoption ofaseprite_pixel_map/aseprite_animationonly reads.jsonfiles that belong to you and lie in the system temp directory or/tmp(or inASEPRITE_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 runchmod 700 ~/.config/aseprite.aseprite_palettestores palettes in~/.config/aseprite-mcp/palettes.json.
Configuration
Variable | Default | Meaning |
|
| WebSocket port (also set it in the MCP Bridge window) |
| unset |
|
|
| Per-command timeout in ms |
| – | Use this token instead of the token file |
| see above | Token file location |
|
| Where |
|
| Folder for automatic backup copies, or |
|
| Backup copies kept per sprite |
|
| Backup copies older than this are deleted |
|
| All backup copies together stay below this size |
| system temp directory (+ | Directories the |
Example with Claude Code:
claude mcp add --scope user --env ASEPRITE_MCP_ALLOW_LUA=1 aseprite -- node /absolute/path/to/aseprite-mcp/server.mjsTroubleshooting
“Aseprite is not connected” – Is the MCP Bridge window open and showing Connected ✓?
“Token rejected” – Run
node server.mjs tokenand paste the value again.Stuck on “Waiting for server” – Is your MCP client running? In Claude Code,
/mcpshows 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 largeraseprite_viewcalls pass a smallerrect.open/savepaths 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-extensionThe test suite has three parts:
File | What it checks | Needs |
| real server ⇄ real |
|
| every extension handler inside a real Aseprite in batch mode ( | Aseprite; found automatically (PATH, Steam, /Applications) or via |
| server, npm package and CHANGELOG carry the same version; the extension's version fits the server ( | – |
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
Bump the version in
package.json,package-lock.json(npm install --package-lock-only) andserver.mjs(VERSION), and add a CHANGELOG.md section.Only if the extension changed: set its new version in
extension/package.jsonandEXTENSION_VERSION(extension/handlers.lua). If the server now relies on a new or changed extension command, also raiseMIN_EXTENSION(server.mjs) to that version – older installed extensions then get a warning. Say in the CHANGELOG whether users need to update the extension.Run
npm testlocally with Aseprite installed – it fails if these numbers don't fit together.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 toolsaseprite_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 copiesARead-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 changedARead-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 guideARead-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 textARead-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 selectionARead-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 infoARead-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 imageARead-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
Scored across 23 tools
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.
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.
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.
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
Related MCP Connectors
Pixel art for your game, from your coding agent. Generate sprites, items and tiles in your game's style (64 to 1024 px), make variants, reskins and N/E/S/W directions, then edit everything in a full pixel art editor that syncs into your project. Works with Claude, Claude Code, Cursor and ChatGPT; sign in with OAuth, no API key.
Generate, edit, style-match, turn, and animate game-ready pixel art at exact sizes.
Turn images into pixel art, extract and remap palettes, and upscale sprites without blur.
Generate pixel art sprites, animations, 8-direction rotations and palettes for games.
Related MCP Servers
- AlicenseCqualityBmaintenanceEnables AI assistants to control Aseprite for drawing and editing images through its API.591,009MIT
- AlicenseAqualityDmaintenanceEnables AI sprite generation and semantic tools for Aseprite, allowing LLMs to create pixel art, add animations, and manage projects with visual feedback.61GPL 3.0
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to drive Aseprite for pixel-art creation, including sprite setup, grid-based drawing, layer/frame/tag management, reference image import, and export, with rendered previews after every mutation.MIT
- AlicenseAqualityBmaintenanceEnables AI agents to create and edit pixel art in a live Aseprite window, with tools for drawing, selection, transformation, and animation.181,597 npm671MIT