# Aseprite MCP Server

A **Model Context Protocol (MCP) server** written in Rust that bridges AI assistants (Claude, GPT, etc.) with the **Aseprite** pixel art editor. This allows AI to create, edit, and export pixel art sprites and animations through natural language instructions.

## Features

### 44 MCP Tools for Full Aseprite Control

| Category | Tools | Description |
|----------|-------|-------------|
| **Sprite** | `create_sprite`, `get_sprite_info`, `resize_sprite`, `crop_sprite`, `flip_sprite`, `rotate_sprite`, `canvas_size`, `duplicate_sprite`, `auto_crop_sprite`, `change_color_mode`, `reverse_frames` | Create, inspect, transform, duplicate, and optimize sprites |
| **Layers** | `list_layers`, `add_layer`, `remove_layer`, `set_layer_property`, `duplicate_layer`, `merge_down_layer`, `flatten_layers` | Full layer management with duplicate, merge, and flatten |
| **Frames** | `list_frames`, `add_frame`, `remove_frame`, `set_frame_duration` | Animation frame management |
| **Tags** | `list_tags`, `create_tag`, `delete_tag` | Animation tag/sequence management |
| **Slices** | `list_slices`, `create_slice`, `delete_slice` | Named regions for game engines: hitboxes, 9-slice UI, pivot points |
| **Cels** | `list_cels`, `move_cel`, `set_cel_opacity`, `clear_cel`, `new_cel` | Fine-grained cel (layer×frame) management for animation |
| **Drawing** | `draw_pixels`, `use_tool`, `get_pixel_data` | Pixel-level drawing and reading with all Aseprite tools |
| **Palette** | `get_palette`, `set_palette_color`, `resize_palette`, `load_palette`, `save_palette`, `color_quantization` | Full palette management with load/save and auto-quantization |
| **Selection** | `select_region`, `deselect`, `select_all`, `invert_selection`, `select_by_color` | Advanced selection operations including color-based selection |
| **Export** | `export_sprite`, `export_spritesheet` | Export to multiple formats and spritesheet with JSON metadata |
| **Effects** | `replace_color`, `outline` | Color replacement and outline effects |
| **Filters** | `brightness_contrast`, `hue_saturation`, `invert_color`, `despeckle` | Image filters for color adjustment and noise reduction |
| **Advanced** | `run_lua_script`, `execute_cli` | Direct Lua scripting and CLI access |

## Architecture

```
┌─────────────┐     stdio (MCP)     ┌──────────────────┐     CLI      ┌──────────┐
│ AI Assistant │◄──────────────────►│ aseprite_mcp     │────────────►│ Aseprite │
│ (Claude etc) │                    │ (Rust MCP Server) │  Lua scripts │ (batch)  │
└─────────────┘                    └──────────────────┘             └──────────┘
```

The server communicates with AI assistants via the MCP protocol over stdio, and controls Aseprite by:
1. Generating Lua scripts dynamically based on tool parameters
2. Executing them via `aseprite --batch --script script.lua`
3. Parsing the JSON output from Aseprite's stdout
4. Returning structured results to the AI assistant

## Installation

### Prerequisites

- **Rust** (1.85+ with edition 2024 support)
- **Aseprite** installed on your system

### Build

```bash
cargo build --release
```

The binary will be at `target/release/aseprite_mcp.exe` (Windows) or `target/release/aseprite_mcp` (Linux/macOS).

### Configure Aseprite Path

The server automatically searches for Aseprite in common locations:

- **Windows**: `C:\Program Files\Aseprite\Aseprite.exe`, Steam path
- **macOS**: `/Applications/Aseprite.app/Contents/MacOS/aseprite`
- **Linux**: PATH, Steam path

To specify a custom path, set the `ASEPRITE_PATH` environment variable:

```bash
export ASEPRITE_PATH="/path/to/aseprite"
```

## MCP Client Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "aseprite": {
      "command": "path/to/aseprite_mcp.exe",
      "env": {
        "ASEPRITE_PATH": "C:\\Program Files\\Aseprite\\Aseprite.exe"
      }
    }
  }
}
```

### VS Code (Copilot)

Add to your `.vscode/mcp.json`:

```json
{
  "servers": {
    "aseprite": {
      "type": "stdio",
      "command": "path/to/aseprite_mcp.exe",
      "env": {
        "ASEPRITE_PATH": "C:\\Program Files\\Aseprite\\Aseprite.exe"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP settings:

```json
{
  "mcpServers": {
    "aseprite": {
      "command": "path/to/aseprite_mcp.exe",
      "env": {
        "ASEPRITE_PATH": "C:\\Program Files\\Aseprite\\Aseprite.exe"
      }
    }
  }
}
```

## Tool Examples

### Create a Sprite
```
Create a 64x64 pixel art sprite with indexed color mode and save it as player.aseprite
```
Tool call: `create_sprite(width=64, height=64, output_path="player.aseprite", color_mode="indexed")`

### Draw Pixels
```
Draw a red pixel at (10, 10) and a blue pixel at (20, 20) on the player sprite
```
Tool call: `draw_pixels(file_path="player.aseprite", pixels=[{x:10,y:10,color:"#ff0000"}, {x:20,y:20,color:"#0000ff"}])`

### Use Drawing Tools
```
Draw a yellow line from (0,0) to (63,63) on the player sprite
```
Tool call: `use_tool(file_path="player.aseprite", tool="line", points=[{x:0,y:0},{x:63,y:63}], color="#ffff00")`

### Export Spritesheet
```
Export the animation as a spritesheet with JSON data
```
Tool call: `export_spritesheet(file_path="player.aseprite", output_image="sheet.png", output_data="sheet.json", sheet_type="rows", columns=4)`

### Run Custom Lua Script
```
Run a custom script to create a checkerboard pattern
```
Tool call: `run_lua_script(script="...", file_path="player.aseprite")`

## Available Drawing Tools

The `use_tool` command supports all Aseprite tools:

| Tool ID | Description |
|---------|-------------|
| `pencil` | Freehand pixel drawing |
| `line` | Straight line |
| `rectangle` | Rectangle outline |
| `filled_rectangle` | Filled rectangle |
| `ellipse` | Ellipse outline |
| `filled_ellipse` | Filled ellipse |
| `paint_bucket` | Flood fill |
| `spray` | Spray/airbrush |
| `eraser` | Erase pixels |
| `contour` | Draw contour |
| `polygon` | Draw polygon |

## Color Format

Colors use hex string format:
- `#rrggbb` — RGB (e.g., `#ff0000` for red)
- `#rrggbbaa` — RGBA with alpha (e.g., `#ff000080` for semi-transparent red)

## WebSocket Plugin (Optional)

For real-time interactive control of a running Aseprite instance, an optional WebSocket plugin is included in `scripts/aseprite-mcp-plugin/`.

### Install the Plugin

1. Copy the `scripts/aseprite-mcp-plugin/` folder to your Aseprite extensions directory:
   - Windows: `%APPDATA%\Aseprite\extensions\`
   - macOS: `~/Library/Application Support/Aseprite/extensions/`
   - Linux: `~/.config/aseprite/extensions/`
2. Restart Aseprite
3. Go to `Help > MCP Server > Connect to MCP Server`

## Project Structure

```
aseprite_mcp/
├── Cargo.toml                          # Rust dependencies
├── README.md                           # This file
├── src/
│   ├── main.rs                         # Entry point, MCP transport setup
│   ├── server.rs                       # MCP server, tool routing & ServerHandler
│   ├── aseprite.rs                     # Aseprite CLI runner (process execution)
│   ├── lua_helpers.rs                  # Reusable Lua snippets (find_layer, etc.)
│   ├── utils.rs                        # Color parsing & validation utilities
│   └── tools/                          # Tool implementations (one file per domain)
│       ├── mod.rs                      # Module re-exports
│       ├── sprite.rs                   # Sprite management (create, info, resize, crop, flip, rotate, canvas, duplicate, auto_crop, color_mode, reverse)
│       ├── layer.rs                    # Layer management (list, add, remove, set properties, duplicate, merge, flatten)
│       ├── frame.rs                    # Frame management (list, add, remove, set duration)
│       ├── tag.rs                      # Animation tag management (list, create, delete)
│       ├── slice.rs                    # Slice management (list, create, delete — 9-slice, pivots, hitboxes)
│       ├── cel.rs                      # Cel management (list, move, opacity, clear, new)
│       ├── drawing.rs                  # Drawing tools (draw_pixels, use_tool, get_pixel_data)
│       ├── palette.rs                  # Palette management (get, set, resize, load, save, quantize)
│       ├── selection.rs                # Selection operations (region, all, invert, by_color, deselect)
│       ├── export.rs                   # Export tools (export_sprite, export_spritesheet)
│       ├── effects.rs                  # Effects (replace_color, outline)
│       ├── filter.rs                   # Image filters (brightness_contrast, hue_saturation, invert, despeckle)
│       └── scripting.rs                # Direct Lua & CLI execution
└── scripts/
    └── aseprite-mcp-plugin/            # Optional Aseprite WebSocket plugin
        ├── package.json
        └── plugin.lua
```

## Tech Stack

- **Rust** (edition 2024)
- **rmcp** 0.3 — MCP protocol framework
- **tokio** — Async runtime
- **serde/serde_json** — JSON serialization
- **tracing** — Structured logging

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `ASEPRITE_PATH` | Full path to Aseprite executable | Auto-detected |
| `ASEPRITE_OUTPUT_DIR` | Default output directory for generated files | Working directory |
| `RUST_LOG` | Log level (`trace`, `debug`, `info`, `warn`, `error`) | `info` |

## License

MIT