aseprite-mcp

A Model Context Protocol (MCP) server for automating Aseprite with Lua scripts. This project provides a FastMCP server that exposes Aseprite functionality to Claude Desktop and other MCP clients, enabling AI-assisted pixel art creation and sprite automation.

Features

• Canvas Management: Create new canvases, add layers and frames
• Drawing Tools: Draw pixels, lines, rectangles, circles with customizable colors and styles
• Fill Operations: Paint bucket tool for area fills
• Export Capabilities: Export sprites to PNG, GIF, and other formats
• Lua Script Generation: Dynamically generates and executes Aseprite Lua scripts
• FastMCP Integration: Seamless integration with Claude Desktop and MCP clients

Setup

Prerequisites

1. Install Aseprite: Download and install Aseprite from aseprite.org

Platform-Specific Aseprite Installation

Windows

• Download from the official website or Steam
• Default installation path: C:\Program Files\Aseprite\Aseprite.exe
• Or install via Chocolatey: choco install aseprite

macOS

• Download from the official website or Steam
• Default path: /Applications/Aseprite.app/Contents/MacOS/aseprite

Linux

• Install via package manager (varies by distribution)
• Ubuntu/Debian: Available in some PPAs
• Arch Linux: pacman -S aseprite or yay -S aseprite
• Flatpak: flatpak install flathub org.aseprite.Aseprite
• Or compile from source following official instructions

Installing aseprite-mcp

Option 1: Install from PyPI (when published)

coming soon

Option 2: Install from source

git clone https://github.com/rkdfx/aseprite-mcp.git
cd aseprite-mcp
pip install -e .

Option 3: Development setup

git clone https://github.com/rkdfx/aseprite-mcp.git
cd aseprite-mcp
pip install -e ".[dev]"

Configuration

1. Automatic Detection: The server will automatically try to find Aseprite in common installation paths
2. Manual Configuration: If Aseprite isn't found automatically, set the ASEPRITE_PATH environment variable:

# Copy the example environment file
cp .env.example .env

# Edit .env and set your Aseprite path
# Windows: ASEPRITE_PATH=C:\Program Files\Aseprite\Aseprite.exe
# macOS: ASEPRITE_PATH=/Applications/Aseprite.app/Contents/MacOS/aseprite
# Linux: ASEPRITE_PATH=/usr/bin/aseprite

Running the Server

# Run as a module
python -m aseprite_mcp

# Or use the installed script
aseprite-mcp

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "aseprite": {
      "command": "python",
      "args": ["-m", "aseprite_mcp"],
      "env": {
        "ASEPRITE_PATH": "/path/to/your/aseprite"
      }
    }
  }
}

Tools Available

Canvas Tools

• create_canvas(width, height, filename) - Create new Aseprite canvas
• add_layer(filename, layer_name) - Add new layer to existing file
• add_frame(filename) - Add new animation frame

Drawing Tools

• draw_pixels(filename, pixels) - Draw individual pixels with colors
• draw_line(filename, x1, y1, x2, y2, color, thickness) - Draw lines
• draw_rectangle(filename, x, y, width, height, color, fill) - Draw rectangles
• draw_ellipse(filename, center_x, center_y, width, height, color, fill) - Draw ellipses
• draw_circle(filename, center_x, center_y, radius, color, fill) - Draw circles
• draw_polygon(filename, points, color, fill) - Draw polygons with multiple vertices
• draw_triangle(filename, x1, y1, x2, y2, x3, y3, color, fill) - Draw triangles
• draw_arc(filename, center_x, center_y, radius, start_angle, end_angle, color, thickness) - Draw arcs
• fill_area(filename, x, y, color) - Fill areas with paint bucket

Export Tools

• export_sprite(filename, output_filename, format) - Export to PNG, GIF, etc.

Example Prompts

The server includes instructional prompts that guide LLMs on how to create complex artwork:

• draw_cloud_example() - Instructions for creating a fluffy cloud using overlapping shapes
• draw_tree_example() - Guide for drawing a tree with trunk and leafy crown
• draw_house_example() - Steps to create a house using geometric shapes
• draw_star_example() - Method for drawing a five-pointed star with precise coordinates
• draw_flower_example() - Instructions for creating a flower with petals, stem, and leaves

These prompts return detailed instructions that help AI agents understand how to combine the basic drawing tools to create complex, recognizable objects.

Architecture

The project uses a modular architecture:

• core/commands.py - Aseprite command execution and Lua script management
• tools/canvas.py - Canvas creation and layer/frame management
• tools/drawing.py - Drawing operations and pixel manipulation
• tools/export.py - Export functionality for various formats

All tools are automatically exposed as MCP tools through the FastMCP decorator system.