aseprite-mcp

An MCP server for Aseprite — create, edit, and export pixel art sprites, animations, and sprite sheets from any AI assistant.

<p align="center"> <img src="assets/demo.gif" alt="Demo — pixel art knight walking animation created with aseprite-mcp" width="256" /> </p>

Drawn and animated entirely via aseprite-mcp tools — no manual pixel editing!

Features

• 43 tools across 11 categories
• Native drawing with configurable brush thickness via app.useTool()
• Pixel-perfect algorithms (Bresenham line, midpoint circle) for thin strokes
• Cross-platform — Windows, macOS, Linux
• Secure — Lua injection prevention, sandboxed execution
• Zero runtime dependencies beyond @modelcontextprotocol/sdk

Tool Overview

Category	Tools	Examples
Sprites	6	create_sprite, resize_sprite, crop_sprite
Layers	4	add_layer, set_layer_properties, list_layers
Frames	4	add_frame, set_frame_duration, list_frames
Tags	3	create_tag, remove_tag, list_tags
Drawing	7	draw_rect, draw_circle, draw_line, draw_ellipse, fill_area, outline, draw_pixels
Transform	5	replace_color, flip_sprite, rotate_sprite, flatten_layers, merge_down
Palette	4	get_palette, set_palette_colors, load_palette, resize_palette
Cels	3	move_cel, set_cel_opacity, clear_cel
Export	3	export_sprite_sheet, export_frame, export_layers
Slices	2	create_slice, remove_slice
Utility	2	run_script, get_aseprite_version

📖 Full parameter reference: docs/API.md

---

Quick Start

Requirements

• Node.js ≥ 18
• Aseprite ≥ 1.3 (aseprite.org)

Install

# npm global
npm install -g aseprite-mcp

# or from source
git clone https://github.com/ayigityol/aseprite-mcp.git
cd aseprite-mcp && npm install && npm run build

Configure

<details> <summary><strong>GitHub Copilot CLI</strong> (~/.copilot/mcp-config.json)</summary>

{
  "mcpServers": {
    "aseprite": {
      "type": "local",
      "command": "node",
      "tools": ["*"],
      "args": ["/path/to/aseprite-mcp/build/index.js"],
      "env": { "ASEPRITE_PATH": "/path/to/aseprite" }
    }
  }
}

</details>

<details> <summary><strong>Claude Desktop</strong> (claude_desktop_config.json)</summary>

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

</details>

<details> <summary><strong>VS Code / Cursor</strong> (.vscode/mcp.json)</summary>

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

</details>

<details> <summary><strong>Installed globally via npm</strong></summary>

{
  "mcpServers": {
    "aseprite": {
      "command": "aseprite-mcp"
    }
  }
}

</details>

Environment Variables

Variable	Description
ASEPRITE_PATH	Path to Aseprite executable. Auto-detected if not set.
DEBUG	Set "true" for verbose stderr logging.

Auto-detection searches standard install paths on all platforms, plus system PATH.

---

Architecture

sequenceDiagram
    participant Client as MCP Client
    participant Server as aseprite-mcp
    participant Aseprite as Aseprite CLI

    Client->>Server: Tool call (JSON-RPC via stdio)
    Server->>Server: Generate Lua script
    Server->>Aseprite: aseprite -b --script temp.lua
    Aseprite->>Aseprite: Execute Lua (headless)
    Aseprite-->>Server: stdout: __RESULT__{"success":true, ...}
    Server->>Server: Parse JSON, cleanup temp file
    Server-->>Client: Tool result

graph LR
    A[Tool Call] --> B{Thickness > 1?}
    B -->|Yes| C[app.useTool<br/>Native Brush]
    B -->|No| D[image:drawPixel<br/>Pixel Algorithms]
    C --> E[Save & Return]
    D --> E

All operations run headless — no GUI window is opened.

---

Docker

# Build
docker build -t aseprite-mcp .

# Run (mount your Aseprite binary + working directory)
docker run --rm -i \
  -v /path/to/aseprite:/usr/local/bin/aseprite:ro \
  -v ./sprites:/sprites \
  aseprite-mcp

# Or use Docker Compose
docker compose up

Aseprite must be mounted into the container. The image packages only the MCP server.

---

Development

npm run build       # Compile TypeScript
npm run watch       # Recompile on changes
npm test            # Run 74 unit tests (vitest)
npm run test:watch  # Watch mode
npm run inspector   # MCP Inspector for interactive testing

---

Security

• luaEscape() — prevents Lua injection by escaping \, ", \n, \r
• luaPath() — normalizes and escapes file paths
• execFile() — argument arrays, no shell interpolation
• pcall() wrapping — all generated Lua scripts have error handlers
• Local only — no data sent to external services

---

Troubleshooting

Problem	Solution
"Aseprite executable not found"	Set ASEPRITE_PATH env var to the full path
Tool returns Aseprite error	Set DEBUG=true to see stderr output
"Layer not found" / "Tag not found"	Names are case-sensitive — use list_layers or list_tags first
Sprite won't save	Ensure the output directory exists

---

License

MIT