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.

Related MCP server: LibreSprite MCP

Tools

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:

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.

Assets

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

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:

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