willibrandon/aseprite-mcp

Aseprite MCP Server

A Model Context Protocol (MCP) server that exposes Aseprite's pixel art and animation capabilities to AI assistants, enabling you to create and edit sprites using natural language.

Features

• Canvas & Layer Management: RGB, Grayscale, and Indexed color modes with multi-layer support and layer deletion
• Drawing Primitives: Pixels, lines, rectangles, circles, polylines, flood fill with batch operations and palette-aware drawing
• Selection Tools: Rectangle, ellipse, select all, copy, cut, paste, move selections with multiple blend modes (replace/add/subtract/intersect)
• Professional Pixel Art Tools:
  • Reference Analysis: Extract palettes, brightness maps, edge detection, and composition guides from images
  • Dithering: 15 patterns including Bayer matrices (2x2, 4x4, 8x8), checkerboard, and textures (grass, water, stone, cloud, brick, dots, diagonal, cross, noise, lines)
  • Palette Management: Set custom palettes (1-256 colors), sort by hue/luminance, analyze color harmonies (complementary/triadic/analogous), and extract from reference images
  • Shading Tools: Apply palette-constrained shading with smooth, hard, or pillow styles and 8 light directions
  • Antialiasing: Detect jagged diagonal edges and suggest intermediate colors for smoother curves (manual or auto-apply)
  • Transform Operations: Flip, rotate, scale, crop, resize canvas, apply outlines, and downsample for pixel art conversion
  • Palette-Aware Drawing: All drawing tools support snapping to nearest palette color using LAB color space
• Animation Tools: Frame durations, tags, frame duplication/deletion, linked cels
• Inspection Tools: Read pixel data with pagination for verification and analysis
• Export Formats: PNG, GIF, JPG, BMP, and spritesheet export (horizontal/vertical/grid layouts)
• Cross-platform: Windows, macOS, Linux
• MCP Integration: Works with Claude Desktop and other MCP clients

Requirements

• Go 1.23+
• Aseprite 1.3.0+ (1.3.10+ recommended)

Quick Start

1. Install

# Clone the repository
git clone https://github.com/willibrandon/aseprite-mcp.git
cd aseprite-mcp

# Build the server
make build

2. Configure

Create ~/.config/aseprite-mcp/config.json:

{
  "aseprite_path": "/path/to/aseprite",
  "temp_dir": "/tmp/aseprite-mcp",
  "timeout": 30,
  "log_level": "info",
  "log_file": "",
  "enable_timing": false
}

Configuration options:

• aseprite_path (required): Absolute path to Aseprite executable. No automatic discovery or environment variables.
• temp_dir (optional): Directory for temporary files. Defaults to /tmp/aseprite-mcp.
• timeout (optional): Command timeout in seconds. Defaults to 30.
• log_level (optional): Logging verbosity (debug, info, warn, error). Defaults to info.
• log_file (optional): Path to log file for persistent logging. If empty, logs only to stderr.
• enable_timing (optional): Enable request tracking and operation timing. Defaults to false.

3. Run

# Run the server (stdio transport)
./bin/aseprite-mcp

# Check health
./bin/aseprite-mcp --health

# Enable debug logging
./bin/aseprite-mcp --debug

Usage with Claude Desktop

Add to your Claude Desktop config:

{
  "mcpServers": {
    "aseprite": {
      "command": "/absolute/path/to/aseprite-mcp"
    }
  }
}

Then use natural language to create sprites:

• "Create a 64x64 sprite and draw a red circle in the center"
• "Add a new layer called 'Background' and fill it with blue"
• "Export the sprite as a PNG"

Available Tools

Canvas & Layer Management

Drawing & Painting

Selection & Clipboard

Note: Selection and clipboard operations persist across MCP tool calls using sprite custom properties (sprite.data) and a hidden clipboard layer. This allows you to create a selection in one tool call, then copy/cut/paste in subsequent calls. Selection bounds are automatically saved and restored, and clipboard content is stored in a hidden __mcp_clipboard__ layer.

Professional Pixel Art

Transform & Filter

Animation

Inspection & Export

Examples

See for a complete working example client that demonstrates all features including canvas creation, animation, dithering, palette management, shading, and antialiasing.

Development

Using Make

# Build (development - fast, no version info)
make build

# Build release (with version and timestamp)
make release

# Run unit tests
make test

# Run unit tests (no cache)
make test-nocache

# Run integration tests (requires configured Aseprite)
make test-integration

# Run integration tests (no cache)
make test-integration-nocache

# Run benchmarks
make bench

# Run linters
make lint

# Generate coverage report
make test-coverage

# Clean build artifacts
make clean

Using Go CLI

# Build (development)
go build -o bin/aseprite-mcp ./cmd/aseprite-mcp

# Build release (with version info)
go build -ldflags "-X main.Version=$(git describe --tags --always --dirty) -X main.BuildTime=$(date -u '+%Y-%m-%d_%H:%M:%S')" -o bin/aseprite-mcp ./cmd/aseprite-mcp

# Run unit tests
go test -v -race -cover ./...

# Run unit tests (no cache)
go test -v -race -cover -count=1 ./...

# Run integration tests
go test -tags=integration -v ./...

# Run integration tests (no cache)
go test -tags=integration -v -count=1 ./...

# Run benchmarks
go test -tags=integration -bench=. -benchmem ./pkg/aseprite ./pkg/tools

# Run linters
go vet ./...
go fmt ./...

# Generate coverage report
go test -v -race -coverprofile=coverage.txt -covermode=atomic ./...
go tool cover -html=coverage.txt -o coverage.html

Performance

All operations complete in under 100ms on typical hardware, with complete workflows finishing in 280-840ms. See for detailed benchmark results.

License