aseprite-mcp

An MCP (Model Context Protocol) server that gives AI agents the ability to create and edit Aseprite sprites programmatically.

An AI can use this server to draw pixels, lines, shapes, manage layers and frames, read back pixel data, inspect the full sprite state, and self-iterate until the result matches the request — all without leaving the chat.

How it works

The server exposes Aseprite's sprite manipulation capabilities as MCP tools that an AI assistant can call. Under the hood it generates Lua scripts that Aseprite executes in batch mode.

Tools

Tool	What it does
create_sprite	Create a new .aseprite file
draw_pixels, draw_line, draw_rectangle, draw_circle	Drawing operations
flood_fill	Flood fill an area
add_layer, remove_layer	Layer management
add_frame, set_frame_duration	Frame/animation control
set_palette_color, resize_canvas	Palette and canvas
export_png, export_gif	Export to image formats
get_sprite_info, inspect_sprite	Read sprite metadata
get_pixel_color, get_palette	Read back pixel data

The AI can read back what it drew, inspect the full sprite state, and self-iterate until it's happy with the result.

Usage

npm run build
npm start        # stdio transport (default)
npm start -- --port 3100   # HTTP server on port 3100

The server runs in stdio mode by default (standard MCP protocol). Pass --port to start an HTTP server instead, allowing remote MCP clients to connect via http://localhost:<port>/mcp.

On startup the server prints its PID, transport mode, and Aseprite binary path to stderr. Use the PID to manage the server process (e.g. kill <pid> to stop).

Requirements

• Aseprite installed

The server auto-detects Aseprite from common install paths. If it's not found, set the ASEPRITE_PATH environment variable to point to the executable:

Platform	Steam	itch.io / Humble / Gumroad
macOS	~/Library/Application Support/Steam/steamapps/common/Aseprite/Aseprite.app/Contents/MacOS/aseprite	/Applications/Aseprite.app/Contents/MacOS/aseprite
Windows	C:\Program Files (x86)\Steam\steamapps\common\Aseprite\Aseprite.exe	C:\Program Files\Aseprite\Aseprite.exe
Linux	~/.steam/steam/steamapps/common/Aseprite/aseprite	/usr/bin/aseprite

export ASEPRITE_PATH="/path/to/aseprite"   # macOS / Linux
set ASEPRITE_PATH="C:\path\to\aseprite.exe"  # Windows

Connecting other agents

This is a standard MCP server — any MCP-compatible client can connect to it. The server runs on stdio transport:

node /path/to/aseprite-mcp/dist/index.js

opencode

Already configured in opencode.json:

{
  "mcp": {
    "aseprite-mcp": {
      "type": "local",
      "command": ["node", "dist/index.js"],
      "enabled": true
    }
  }
}

Claude Code

Add to ~/.claude/config.json or project CLAUDE.md:

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

Cursor

Create .cursor/mcp.json in the project root:

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

VS Code (GitHub Copilot)

Add to .vscode/settings.json:

{
  "github.copilot.chat.agent.mcpServers": {
    "aseprite-mcp": {
      "command": "node",
      "args": ["path/to/aseprite-mcp/dist/index.js"],
      "env": {
        "ASEPRITE_PATH": "/path/to/aseprite"
      }
    }
  }
}

Over HTTP (remote clients)

Start the server with a port:

npm start -- --port 3100

Then point any MCP client to http://localhost:3100/mcp:

{
  "mcpServers": {
    "aseprite-mcp": {
      "url": "http://localhost:3100/mcp",
      "type": "http",
      "headers": {}
    }
  }
}

Health check: http://localhost:3100/health

Cline / Roo Code

Add to cline_mcp_settings.json or roo_mcp_settings.json:

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

Using ASEPRITE_PATH with the MCP config

If the auto-detection fails, pass the environment variable in the MCP server config:

{
  "env": {
    "ASEPRITE_PATH": "/Applications/Aseprite.app/Contents/MacOS/aseprite"
  }
}

See mcp.example.json for all config variants.

Example

An AI is asked to "draw a red heart on a 16x16 canvas":

1. Create the sprite

→ create_sprite(file: "heart.aseprite", width: 16, height: 16)
← Created sprite: heart.aseprite (16x16, rgb)

2. Draw the heart using rectangles and flood fill

The AI calls a series of drawing tools — first a red rectangle for the base, then flood fills to shape it into a heart.

→ draw_rectangle(file: "heart.aseprite", x: 2, y: 5, w: 12, h: 6, color: "#ff0000", fill: true)
← Rectangle drawn on heart.aseprite
→ flood_fill(file: "heart.aseprite", x: 2, y: 4, color: "#ff0000")
← Flood fill done on heart.aseprite
→ flood_fill(file: "heart.aseprite", x: 13, y: 4, color: "#ff0000")
← Flood fill done on heart.aseprite

3. Inspect the result

→ get_pixel_color(file: "heart.aseprite", x: 4, y: 4)
← Color at (4, 4): #ff0000ff (rgba: 255, 0, 0, 255)
→ export_png(file: "heart.aseprite", output: "heart.png")
← Exported PNG: heart.png

The AI reads back pixel data, verifies the shape, and exports the final sprite — all autonomously.

<!-- result . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . # # # . . # # # . . . . . . . # # # # # # # # # # . . . . . # # # # # # # # # # # # . . . . # # # # # # # # # # # # . . . . # # # # # # # # # # # # . . . . . # # # # # # # # # # . . . . . . . # # # # # # # # . . . . . . . . . # # # # # # . . . . . . . . . . . # # # # . . . . . . . . . . . . . # # . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . -->

Assets

The assets/ directory contains sample sprites generated with this server:

File	Size	Description
player.aseprite	64×64	Player character with head, body, arms, hands, legs — 14 animated frames (idle/walk/attack)
kitten_plane.aseprite	96×64	Orange kitten in a vintage toy airplane with aviator helmet and goggles
heart.aseprite	16×16	Heart pickup
coin.aseprite	16×16	Gold coin
enemy.aseprite	16×16	Spike-top enemy
platform.aseprite	32×16	Dirt platform with grass

Each .aseprite file has a scaled .png export. Open them in Aseprite to edit, or use the PNGs directly in a game.

opencode-office

The opencode-office/ directory is a pixel-art agent HQ for opencode, inspired by Pixel Agents. It visualizes AI agents as animated characters in a virtual office.

6 agent colors — blue, green, red, purple, orange, teal — each with 8 animation frames across 3 states:

State	Frames	Duration	Description
idle	2	400ms	Subtle breathing bounce
walk	4	150ms	Leg alternation cycle
work	2	500ms	Typing arm motion

Plus furniture: desk (24×16), chair (12×12), computer monitor (8×6 with glow), potted plant (12×12), and tileable floor/wall tiles.

Using the viewer

Open opencode-office/index.html in any browser:

• Click + Agent / - Agent to spawn or remove pixel agents (up to 9 desks)
• Agents auto-animate: work at their desk, take random walks, and return
• Click an agent to inspect its name, state, and recent activity
• Debug mode overlays state and position on each character

Regenerating office sprites

ASEPRITE_PATH="/path/to/aseprite" node scripts/generate-characters.cjs
ASEPRITE_PATH="/path/to/aseprite" node scripts/generate-furniture.cjs

License

MIT