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.
Example scene created using pixel-mcp: 64x64 indexed sprite with custom 16-color palette, demonstrating drawing primitives (rectangles, circles) and palette management.
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
- Color Quantization: Reduce images to 2-256 colors using median_cut, k-means, or octree algorithms with optional Floyd-Steinberg dithering
- Automatic Shading: Apply geometry-based shading with 3 styles (cell/smooth/soft), 8 light directions, and adjustable intensity
- Dithering: 16 patterns including Bayer matrices (2x2, 4x4, 8x8), Floyd-Steinberg, 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/pixel-mcp.git
cd pixel-mcp
# Build the server
make build
2. Configure
Create ~/.config/pixel-mcp/config.json:
{
"aseprite_path": "/path/to/aseprite",
"temp_dir": "/tmp/pixel-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/pixel-mcp.timeout(optional): Command timeout in seconds. Defaults to 30.log_level(optional): Logging verbosity (debug,info,warn,error). Defaults toinfo.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 tofalse.
3. Run
# Run the server (stdio transport)
./bin/pixel-mcp
# Check health
./bin/pixel-mcp --health
# Enable debug logging
./bin/pixel-mcp --debug
Usage with Claude Desktop
Add to your Claude Desktop config:
{
"mcpServers": {
"aseprite": {
"command": "/absolute/path/to/pixel-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 examples/ 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/pixel-mcp ./cmd/pixel-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/pixel-mcp ./cmd/pixel-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 docs/BENCHMARKS.md for detailed benchmark results.
