aseprite-mcp

MCP server for controlling Aseprite from Codex. It wraps Aseprite's native CLI plus Lua scripting so Codex can create pixel art, edit sprites, build animation frames, inspect files, and export PNG/GIF/sprite sheets.

The broad capability path is intentional:

• High-level tools cover common pixel-art workflows.
• aseprite_command_sequence exposes Aseprite's built-in app.command.<CommandId>(params) action system.
• aseprite_cli exposes any Aseprite CLI flag.
• aseprite_run_lua exposes Aseprite's Lua API, so features not modeled by the high-level schema are still reachable.

Requirements

• Node.js 20+
• Aseprite installed locally
• Aseprite executable available as one of:
  • ASEPRITE_PATH=/path/to/aseprite
  • aseprite on PATH
  • macOS user app path such as ~/Applications/Aseprite.app/Contents/MacOS/aseprite
  • macOS app path such as /Applications/Aseprite.app/Contents/MacOS/aseprite

This machine has Aseprite at /Users/sunjiaxiang/Applications/Aseprite.app/Contents/MacOS/aseprite.

Build

cd /Users/sunjiaxiang/workspace/tmp/aseprite-mcp
npm install
npm run build
npm test
npm run test:e2e

Add To Codex

Use the Codex CLI:

codex mcp add aseprite -- node /Users/sunjiaxiang/workspace/tmp/aseprite-mcp/dist/index.js

If Aseprite is not on PATH, pass the executable path:

codex mcp add aseprite \
  --env ASEPRITE_PATH=/Users/sunjiaxiang/Applications/Aseprite.app/Contents/MacOS/aseprite \
  -- node /Users/sunjiaxiang/workspace/tmp/aseprite-mcp/dist/index.js

After adding the server, restart Codex so the new MCP tools are loaded.

Equivalent ~/.codex/config.toml shape is:

[mcp_servers.aseprite]
command = "node"
args = ["/Users/sunjiaxiang/workspace/tmp/aseprite-mcp/dist/index.js"]

[mcp_servers.aseprite.env]
ASEPRITE_PATH = "/Users/sunjiaxiang/Applications/Aseprite.app/Contents/MacOS/aseprite"

Tools

aseprite_status

Resolves Aseprite and reports version/configuration.

aseprite_list_commands

Lists Aseprite command IDs extracted from upstream src/app/commands/commands_list.h, such as NewFile, SpriteSize, Flip, HueSaturation, NewFrame, SaveFileAs, and ExportSpriteSheet.

aseprite_command_sequence

Runs Aseprite built-in actions through Lua as app.command.<CommandId>(params). Use this for menu/action behavior such as creating files, resizing sprites, flipping, changing color mode, adding frames/layers, applying filters, and saving. It accepts dryRun: true to inspect the generated Lua.

aseprite_create_sprite

Creates a new sprite from structured JSON drawing operations. Supports pixel, rect, line, circle, text, matrix, and embedded lua operations. Use dryRun: true to inspect generated Lua without launching Aseprite.

aseprite_run_lua

Runs inline Lua or a .lua file through Aseprite's --script, optionally after opening input sprites and passing app.params.

aseprite_cli

Runs raw Aseprite CLI args. This is the escape hatch for all native Aseprite features.

aseprite_export

Exports an existing sprite/image using common flags such as --save-as, --sheet, --data, --trim, --frame-range, --layer, and --tag.

aseprite_sprite_info

Opens a sprite and returns width, height, frames, layers, and tags.

Example Codex Prompt

After registration and restart, ask Codex:

Use the aseprite MCP to create a 16x16 four-frame bouncing green slime.
Save the source as /Users/sunjiaxiang/workspace/tmp/slime.aseprite and export a GIF to /Users/sunjiaxiang/workspace/tmp/slime.gif.

Codex can call aseprite_create_sprite for the source file and aseprite_export or aseprite_cli for the GIF.

For native Aseprite actions:

Use the aseprite MCP command sequence tool to create a sprite in scriptBefore, run Aseprite's Flip and NewFrame commands, draw a few pixels in scriptAfter, then save it as /Users/sunjiaxiang/workspace/tmp/action-test.aseprite.

Codex can call aseprite_list_commands to discover command IDs and aseprite_command_sequence to run them.

Structured Sprite Example

examples/slime.json contains a four-frame sample. To inspect the Lua generated from it:

npm run build
node examples/create-slime.mjs

If Aseprite is installed:

node examples/create-slime.mjs > /tmp/slime.lua
/Applications/Aseprite.app/Contents/MacOS/aseprite --batch --script /tmp/slime.lua

Or through the MCP tool:

{
  "dryRun": false,
  "spec": {
    "width": 16,
    "height": 16,
    "output": "/Users/sunjiaxiang/workspace/tmp/test.aseprite",
    "operations": [
      {
        "type": "rect",
        "x": 2,
        "y": 2,
        "width": 12,
        "height": 12,
        "color": "#ffcc00ff"
      }
    ]
  }
}

Command Sequence Example

This dry-run request generates a Lua script that calls Aseprite's native command system. Some UI/document commands can be disabled in --batch; set requireEnabled: false only when you have verified the command still behaves correctly headlessly.

{
  "dryRun": true,
  "validateKnownCommands": true,
  "scriptBefore": "local sprite = Sprite(16, 16, ColorMode.RGB); app.activeSprite = sprite; app.activeImage:drawPixel(1, 1, Color{r=255,g=0,b=0,a=255})",
  "actions": [
    {
      "command": "Flip",
      "params": {
        "orientation": "horizontal"
      },
      "requireEnabled": false
    },
    {
      "command": "NewFrame",
      "params": {}
    }
  ],
  "scriptAfter": "app.activeImage:drawPixel(2, 2, Color{r=0,g=0,b=255,a=255})",
  "saveAs": "/Users/sunjiaxiang/workspace/tmp/action-test.aseprite"
}

For commands with newer or version-specific IDs, keep validateKnownCommands false and let the installed Aseprite validate the command at runtime.

Notes

• transparentColor maps to Aseprite's transparent color index/mask color. Pass a numeric string like "0" or provide a palette and a matching hex color.
• Command parameters are passed as a Lua table to Aseprite. Aseprite's CommandWithNewParams supports booleans, numbers, strings, rectangles/sizes, colors, and enum strings for many commands.
• The MCP server does not reimplement Aseprite. It uses Aseprite itself for file creation, scripting, export, and conversion.
• When no Aseprite executable is available, tests still verify TypeScript, Lua generation, and stdio MCP tool registration.
• Full end-to-end image generation requires a real Aseprite executable. On this machine, /Users/sunjiaxiang/Applications/Aseprite.app/Contents/MacOS/aseprite is available and used for smoke tests.
• npm run test:e2e creates real .aseprite files and exports PNGs through the MCP server.