### Local Installation Configuration

Source: https://github.com/diivi/aseprite-mcp/blob/main/README.md

Example configuration for local installation using 'uv' package manager. Ensure Python 3.13+ and 'uv' are installed, and ASEPRITE_PATH is set if Aseprite is not on your PATH.

```json
{
  "mcpServers": {
      "aseprite": {
          "command": "/opt/homebrew/bin/uv",
          "args": [
              "--directory",
              "/path/to/repo",
              "run",
              "-m",
              "aseprite_mcp"
          ]
      }
  }
}
```

--------------------------------

### Verify Installation

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Run the aseprite_mcp module with the --help flag to verify the installation.

```bash
uv run -m aseprite_mcp --help
```

--------------------------------

### Clone and Install Aseprite MCP

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Clone the repository and install dependencies using uv.

```bash
git clone https://github.com/divyansh/aseprite-mcp.git
cd aseprite-mcp
uv sync
```

--------------------------------

### Install Dependencies with uv

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Install project dependencies using the 'uv sync' command.

```bash
uv sync
```

--------------------------------

### Get Animation Workflow Guide

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Retrieves a concise, markdown-formatted guide for optimized animation workflows. Specify the use case for tailored advice.

```python
async def animation_workflow_guide(use_case: str = "character") -> str:
    # Function implementation omitted for brevity
    pass
```

--------------------------------

### Docker Compose up (development)

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Starts the Aseprite MCP development service using the 'dev' profile.

```bash
docker-compose --profile dev up aseprite-mcp-dev
```

--------------------------------

### Docker Setup with .env File

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Configure Docker to use a .env file for Steam credentials to enable automatic Aseprite installation. The ASEPRITE_PATH will be automatically set after installation.

```dotenv
STEAM_USERNAME=your_username
STEAM_PASSWORD=your_password
```

```bash
docker run --rm -i --env-file .env aseprite-mcp:latest
```

--------------------------------

### Docker Compose up (production)

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Starts the Aseprite MCP service defined in docker-compose.yml for production.

```bash
docker-compose up aseprite-mcp
```

--------------------------------

### Run Aseprite MCP container (development mode)

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Starts the container with a volume mount, mapping the current directory to '/app' for development.

```bash
docker run -it --rm -v $(pwd):/app aseprite-mcp:latest
```

--------------------------------

### Start and Stop Preview Server

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Starts and stops a local HTTP server to preview exported Aseprite files. Specify the directory to serve and the port number.

```python
async def start_preview_server(directory: str, port: int = 8000) -> str:
    # Function implementation omitted for brevity
    pass
```

```python
async def stop_preview_server(port: int = 8000) -> str:
    # Function implementation omitted for brevity
    pass
```

```python
await start_preview_server("./exports", port=8000)
# Navigate to http://localhost:8000 in a browser to view files

await stop_preview_server(port=8000)
```

--------------------------------

### Build and Run Docker Image

Source: https://github.com/diivi/aseprite-mcp/blob/main/README.md

Build the Docker image for aseprite-mcp and run it interactively. Ensure you have Docker installed.

```bash
docker build -t aseprite-mcp:latest .
docker run -it --rm aseprite-mcp:latest
```

--------------------------------

### Example .env File for ASEPRITE_PATH

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

The server automatically loads environment variables from a .env file located in the project root. This example shows how to set the ASEPRITE_PATH within such a file.

```dotenv
ASEPRITE_PATH=/opt/homebrew/bin/aseprite
```

--------------------------------

### Run Aseprite MCP container (basic)

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Starts a basic Aseprite MCP container. The container will be removed upon exit.

```bash
docker run -it --rm aseprite-mcp:latest
```

--------------------------------

### Configure MCP Server in .mcp.json

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Define the Model Context Protocol server setup for aseprite. Use 'stdio' for command-line tools.

```json
{
  "mcpServers": {
    "aseprite": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "-m",
        "aseprite_mcp"
      ],
      "env": {}
    }
  }
}
```

--------------------------------

### MCP Client Configuration

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER_SETUP_SUMMARY.md

Example JSON configuration for an MCP client to connect to the Aseprite Docker container.

```json
{
  "mcpServers": {
    "aseprite": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "aseprite-mcp:latest"
      ]
    }
  }
}
```

--------------------------------

### animation_workflow_guide

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Provides a concise English guide for optimized animation workflows, tailored to different use cases.

```APIDOC
## animation_workflow_guide

### Description
Return a concise English guide for optimized animation workflows.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
Python (async function)

### Endpoint
N/A

### Parameters
- **use_case** (str) - Optional - Workflow type: "character", "environment", or other (Default: "character")

### Returns
Markdown-formatted workflow guide

### Example
```python
await animation_workflow_guide(use_case="environment")
```
```

--------------------------------

### Run Aseprite MCP container (interactive shell)

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Starts the container and opens an interactive bash shell, overriding the default entrypoint.

```bash
docker run -it --rm --entrypoint /bin/bash aseprite-mcp:latest
```

--------------------------------

### Start Aseprite MCP Server

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Launch the Aseprite MCP server using either `uv` or Python directly. The server communicates via stdio using the Model Context Protocol.

```bash
# Via uv
uv run -m aseprite_mcp
```

```bash
# Via Python directly
python -m aseprite_mcp
```

--------------------------------

### Run Docker with Steam Credentials

Source: https://github.com/diivi/aseprite-mcp/blob/main/README.md

Run the Docker container and provide Steam credentials via a .env file to install Aseprite. Ensure the .env file contains STEAM_USERNAME and STEAM_PASSWORD.

```powershell
# Create a .env with STEAM_USERNAME/STEAM_PASSWORD (and optional STEAM_GUARD_CODE)
# Then
docker run --rm -i --env-file .env aseprite-mcp:latest
```

--------------------------------

### Run Docker Compose Services

Source: https://github.com/diivi/aseprite-mcp/blob/main/README.md

Deploy aseprite-mcp using Docker Compose for production or development. This requires a Docker Compose setup.

```bash
# Production
docker-compose up aseprite-mcp

# Development mode
docker-compose --profile dev up aseprite-mcp-dev
```

--------------------------------

### Aseprite MCP Export Workflow Example

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-export.md

Demonstrates a recommended iterative workflow for art creation using Aseprite MCP. This includes creating a canvas, drawing, previewing with `export_frame`, and final export with `export_sprite`. Frequent previewing is crucial for effective drawing.

```python
# 1. Create and draw
await create_canvas(32, 32, "sprite.aseprite")
await add_layer("sprite.aseprite", "body")
await draw_pixels_at("sprite.aseprite", "body", 1, [{"x": 5, "y": 5, "color": "#FF0000"}])

# 2. Preview at scale
await export_frame("sprite.aseprite", 1, "preview.png", scale=8)
# Open preview.png to inspect

# 3. Iterate: modify, preview again
await draw_pixels_at("sprite.aseprite", "body", 1, [{"x": 6, "y": 5, "color": "#FF0000"}])
await export_frame("sprite.aseprite", 1, "preview.png", scale=8)

# 4. Final export when satisfied
await export_sprite("sprite.aseprite", "final.png")
```

--------------------------------

### Python: Example of Invalid Parameter Value Error

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/errors.md

This example shows how providing an invalid width (0) to `create_canvas` results in an error message indicating that dimensions must be positive.

```python
result = await create_canvas(0, 32, "sprite.aseprite")
# Returns: "Width and height must be > 0"
```

```python
if width <= 0 or height <= 0:
    print("Width and height must be > 0")
else:
    await create_canvas(width, height, filename)
```

--------------------------------

### Handle File Not Found Error

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/errors.md

This example demonstrates handling a 'File Not Found' error when attempting to draw pixels. It shows the direct error return and a recovery strategy involving checking file existence.

```python
result = await draw_pixels("nonexistent.aseprite", [{"x": 0, "y": 0, "color": "#FF0000"}])
# Returns: "File nonexistent.aseprite not found"
```

```python
import os
if not os.path.exists(filename):
    print(f"Error: sprite file does not exist")
else:
    await draw_pixels(filename, pixels)
```

--------------------------------

### Create Cel if Missing for Drawing

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/errors.md

This example demonstrates how to avoid 'No Active Cel' errors by using `draw_pixels_at` with `create_if_missing=True`. This ensures a cel exists before drawing.

```python
# Instead of draw_pixels (which uses active cel):
await draw_pixels_at("sprite.aseprite", "body", 1, pixels, create_if_missing=True)
```

--------------------------------

### Example Usage of export_spritesheet

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-export.md

Demonstrates how to call the export_spritesheet function with various parameters to create a packed sprite sheet with JSON data, scaling, padding, and filtering by tag name.

```python
await export_spritesheet(
    "sprite.aseprite",
    "spritesheet.png",
    sheet_type="packed",
    data_filename="spritesheet.json",
    scale=1,
    padding=1,
    tag_name="walk"
)
```

--------------------------------

### Python: Path Traversal Error Example and Recovery

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/errors.md

Demonstrates how attempting to export a frame to a path containing '..' components triggers a 'parent directory traversal not allowed' error. It also shows the correct way to specify relative paths.

```python
result = await export_frame("sprite.aseprite", 1, "../../sensitive.png")
# Returns: "Invalid filename: parent directory traversal not allowed"
```

```python
# Use relative paths only, no .. components
await export_frame("sprite.aseprite", 1, "output/frame.png")  # OK
await export_frame("sprite.aseprite", 1, "../frame.png")       # Error
```

--------------------------------

### Draw Line

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-drawing.md

Draws a line on the Aseprite file. Specify start and end coordinates, color, and thickness. The algorithm uses Bresenham's line algorithm with a circular brush for thickness.

```python
async def draw_line(
    filename: str,
    x1: int,
    y1: int,
    x2: int,
    y2: int,
    color: str = "#000000",
    thickness: int = 1
) -> str:
    pass
```

```python
await draw_line("sprite.aseprite", 0, 0, 10, 10, color="#0000FF", thickness=2)
```

--------------------------------

### Handle Layer Not Found Error

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/errors.md

This example addresses the 'Layer Not Found' error. It shows the error return from deleting a non-existent layer and a recovery strategy that checks for layer existence using sprite information.

```python
result = await delete_layer("sprite.aseprite", "nonexistent_layer")
# Returns: "Failed to delete layer: Layer not found"
```

```python
# Get sprite info to check available layers
info = json.loads(await get_sprite_info("sprite.aseprite"))
layer_names = [layer["name"] for layer in info["layers"]]
if layer_name not in layer_names:
    print(f"Layer '{layer_name}' not found. Available: {layer_names}")
else:
    await delete_layer("sprite.aseprite", layer_name)
```

--------------------------------

### Set ASEPRITE_PATH Environment Variable

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Set the ASEPRITE_PATH environment variable to specify the location of the Aseprite executable. This is useful if Aseprite is not in your system's PATH or if you have multiple installations.

```bash
# macOS (Homebrew)
export ASEPRITE_PATH="/opt/homebrew/bin/aseprite"
```

```bash
# Linux
export ASEPRITE_PATH="/usr/bin/aseprite"
```

```bash
# Windows
export ASEPRITE_PATH="C:\Program Files\Aseprite\aseprite.exe"
```

--------------------------------

### Create .env File

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Optionally create a .env file to specify the path to the Aseprite binary if it's not in your system's PATH.

```bash
echo 'ASEPRITE_PATH=/path/to/aseprite' > .env
```

--------------------------------

### Get Sprite Information

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/errors.md

Use the get_sprite_info() function to verify the structure of a sprite, particularly when encountering indexing errors.

```lua
get_sprite_info()
```

--------------------------------

### Crop Canvas

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Trims the canvas to a specific rectangular region defined by its starting coordinates (x, y) and dimensions (width, height).

```python
async def crop_canvas(
    filename: str,
    x: int, y: int,
    width: int, height: int
) -> str
```

--------------------------------

### Build Docker Image

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER_SETUP_SUMMARY.md

Use the provided script or the manual docker build command to create the Docker image. Ensure you are in the project root directory.

```bash
# Using provided script
./build-docker.sh
```

```bash
# Or manually
docker build -t aseprite-mcp:latest .
```

--------------------------------

### fill_area

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-drawing.md

Fills a connected region with a specified color starting from a given point. This function uses a flood fill algorithm.

```APIDOC
## fill_area

### Description
Fill a region with color using the paint bucket tool.

### Parameters
#### Path Parameters
- **filename** (str) - Required - Aseprite file to modify
- **x** (int) - Required - X coordinate to fill from
- **y** (int) - Required - Y coordinate to fill from
- **color** (str) - Optional - Hex color code. Defaults to "#000000".

### Returns
Status message string

### Example
```python
await fill_area("sprite.aseprite", 16, 16, color="#FF0000")
```
```

--------------------------------

### Build Docker Image

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Choose a method to build the Docker image for Aseprite MCP. Ensure the build script is executable before running.

```bash
# Option 1: Build script (Linux/macOS)
chmod +x build-docker.sh
./build-docker.sh
```

```powershell
# Option 2: Build script (Windows)
.\build-docker.ps1
```

```bash
# Option 3: Manual build
docker build -t aseprite-mcp:latest .
```

--------------------------------

### Fill Area with Color

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-drawing.md

Fills a connected region with a specified color starting from a given point. Uses a flood fill algorithm.

```python
async def fill_area(filename: str, x: int, y: int, color: str = "#000000") -> str

```

```python
await fill_area("sprite.aseprite", 16, 16, color="#FF0000")

```

--------------------------------

### Basic Aseprite MCP Workflow

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Demonstrates a basic workflow for creating a sprite, adding layers, drawing pixels, and exporting the result using Aseprite MCP.

```python
# Create a sprite
await create_canvas(32, 32, "sprite.aseprite")

# Add layers
await add_layer("sprite.aseprite", "body")

# Draw some pixels
await draw_pixels_at("sprite.aseprite", "body", 1, [
    {"x": 5, "y": 5, "color": "#FF0000"},
    {"x": 6, "y": 5, "color": "#FF0000"}
])

# Preview the result
await export_frame("sprite.aseprite", 1, "preview.png", scale=8)

# Export final sprite
await export_sprite("sprite.aseprite", "output.png")
```

--------------------------------

### start_preview_server / stop_preview_server

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Manages a local HTTP server to preview exported files. Use `start_preview_server` to begin serving files and `stop_preview_server` to halt the service.

```APIDOC
## start_preview_server / stop_preview_server

### Description
Serve exported files over local HTTP for quick preview.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Method
Python (async function)

### Endpoint
N/A

### Parameters for `start_preview_server`:
- **directory** (str) - Required - The directory containing files to serve.
- **port** (int) - Optional - The port to run the server on (Default: 8000).

### Parameters for `stop_preview_server`:
- **port** (int) - Optional - The port of the server to stop (Default: 8000).

### Returns
Status message string.

### Example
```python
await start_preview_server("./exports", port=8000)
# Navigate to http://localhost:8000 in a browser to view files

await stop_preview_server(port=8000)
```
```

--------------------------------

### Get Sprite Palette

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-palette.md

Retrieve the active sprite palette as a JSON array of hex color strings. Requires the filename of the Aseprite file.

```python
async def get_palette(filename: str) -> str

palette_json = await get_palette("sprite.aseprite")
# Returns: '["#000000", "#FFFFFF", "#FF0000", ...]'
```

--------------------------------

### Manually build Docker image

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Builds the Docker image with the tag 'aseprite-mcp:latest' from the current directory.

```bash
docker build -t aseprite-mcp:latest .
```

--------------------------------

### Propagate Frame to Frame Range

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-animation.md

Copies all cels from a source frame to a contiguous range of target frames. Specify the start and end frames for the propagation.

```python
async def propagate_frame_to_range(
    filename: str,
    source_frame: int,
    start_frame: int,
    end_frame: int
) -> str
```

--------------------------------

### Get and Use Palette Colors for Drawing

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-palette.md

Retrieves the current palette from an Aseprite file, parses it, and then uses a specific color from the palette for drawing operations.

```python
# Pick colors from the palette
palette_json = await get_palette("sprite.aseprite")
palette = json.loads(palette_json)
skin_color = palette[5]

# Draw using those colors
await draw_pixels_at("sprite.aseprite", "body", 1, [
    {"x": 10, "y": 10, "color": skin_color}
])
```

--------------------------------

### Build and Run Aseprite MCP in Docker

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Commands to build the Docker image and run the container. Supports running with volumes for persistent data or using docker-compose.

```bash
# Build
docker build -t aseprite-mcp:latest .

# Run
docker run -it --rm aseprite-mcp:latest

# Or with volumes
docker run -it --rm -v /path/to/sprites:/workspace aseprite-mcp:latest

# Or with docker-compose
docker-compose up aseprite-mcp
```

--------------------------------

### Run container with environment file (PowerShell)

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Runs the Aseprite MCP container using credentials from a .env file, recommended for security.

```powershell
# Windows PowerShell
# Reads credentials from a .env file (recommended)
docker run --rm -i --env-file .env aseprite-mcp:latest
```

--------------------------------

### Python: Example of Invalid Blend Mode Error

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/errors.md

This snippet demonstrates how an invalid blend mode string triggers an error message listing the available valid modes.

```python
result = await set_layer_blend_mode("sprite.aseprite", "body", "invalid_mode")
# Returns: "Unknown blend mode 'invalid_mode'. Valid modes: normal, darken, ..."
```

--------------------------------

### Configure Claude Client for Aseprite MCP

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Add server configuration to your Claude client, specifying the command and arguments to launch the aseprite-mcp server.

```json
{
  "mcpServers": {
    "aseprite": {
      "command": "/opt/homebrew/bin/uv",
      "args": [
        "--directory",
        "/path/to/aseprite-mcp",
        "run",
        "-m",
        "aseprite_mcp"
      ]
    }
  }
}
```

--------------------------------

### Get Tilemap Information

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Retrieves tile size, tile count, and map dimensions for a specified tilemap layer as a JSON string. Use this to understand the structure of your tilemaps.

```python
async def get_tilemap_info(filename: str, layer_name: str) -> str
```

--------------------------------

### Get Pixel Color

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Reads the RGBA color of a single pixel at specified coordinates within a layer and frame. Returns a hex color string with RGBA components.

```python
async def get_pixel_color(
    filename: str,
    x: int, y: int,
    layer_name: str = "",
    frame_index: int = 1
) -> str
```

--------------------------------

### Run Aseprite MCP with Environment File

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Command to run the Aseprite MCP container using an environment file for configuration, such as Steam credentials.

```bash
docker run --rm -i --env-file .env aseprite-mcp:latest
# Set STEAM_USERNAME and STEAM_PASSWORD in .env
```

--------------------------------

### Palette API

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Manages color palettes, including getting, setting, listing presets, applying presets, generating color ramps, quantizing colors, and remapping colors.

```APIDOC
## Palette API

### Description
Functions for color palette management, including getting, setting, applying presets, generating ramps, and remapping colors.

### Methods
- `get_palette`
- `set_palette`
- `list_palette_presets`
- `apply_palette_preset`
- `generate_color_ramp`
- `quantize_to_palette`
- `remap_colors_in_cel_range`
- `set_color_mode`
```

--------------------------------

### Run Aseprite MCP Docker Container

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Execute the Aseprite MCP Docker container. Use volume mounts for persistent storage of sprites.

```bash
docker run -it --rm aseprite-mcp:latest
```

```bash
docker run -it --rm -v /path/to/sprites:/workspace aseprite-mcp:latest
```

--------------------------------

### Clone Repository

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Clone the aseprite-mcp repository to your local machine.

```bash
git clone https://github.com/divyansh/aseprite-mcp.git
cd aseprite-mcp
```

--------------------------------

### Get Sprite Info

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-animation.md

Retrieves sprite metadata including dimensions, color mode, frame durations, layers, and tags as a JSON string. Requires the filename of the Aseprite file.

```python
async def get_sprite_info(filename: str) -> str
```

--------------------------------

### Import Image and Quantize to Palette

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-palette.md

Imports an external image as a new layer into an Aseprite file and then quantizes that layer's colors to match the sprite's current palette.

```python
# Import a background image
await import_image_as_layer("sprite.aseprite", "ref.png", "ref")

# Quantize it to the palette
await quantize_to_palette("sprite.aseprite", layer_name="ref")
```

--------------------------------

### Run Docker Container

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER_SETUP_SUMMARY.md

Commands to run the Aseprite MCP Docker container. Options include basic run, development mode with volume mounting, and accessing an interactive shell.

```bash
# Basic run
docker run -it --rm aseprite-mcp:latest
```

```bash
# Development mode with volume mount
docker run -it --rm -v $(pwd):/app aseprite-mcp:latest
```

```bash
# Interactive shell
docker run -it --rm --entrypoint /bin/bash aseprite-mcp:latest
```

--------------------------------

### Get Tile at Position

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Reads the index of the tile occupying a specific cell in a tilemap layer's grid for a given frame. Returns the tile index at the specified column and row.

```python
async def get_tile_at(
    filename: str,
    layer_name: str,
    frame_index: int,
    col: int,
    row: int
) -> str
```

--------------------------------

### Execute build script on Linux/macOS

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Runs the build-docker.sh script to build the Docker image on Linux or macOS.

```bash
./build-docker.sh
```

--------------------------------

### Run Lua Script with Debug Output

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/errors.md

Shows how to execute a Lua script that includes debug output using `print()`. This is useful for testing and debugging Aseprite API calls.

```python
# Test script with debug output
script = """
local spr = app.activeSprite
if not spr then
    print("ERROR:No sprite")
    return
end
print("Sprite: " .. spr.width .. "x" .. spr.height)
"""
result = await run_lua_script(script, "sprite.aseprite")
```

--------------------------------

### Get Pixels in Rectangular Region

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Reads all pixel colors within a specified rectangular area of a layer and frame. Returns a JSON array of pixel objects, each containing coordinates and RGBA values.

```python
async def get_pixels_rect(
    filename: str,
    x: int, y: int,
    width: int, height: int,
    layer_name: str = "",
    frame_index: int = 1
) -> str
```

--------------------------------

### Apply Palette Preset

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-effects.md

Applies a predefined color palette to the Aseprite file. This is the first step in a palette-respecting workflow.

```python
# Use a preset
await apply_palette_preset("sprite.aseprite", "pico8")
```

--------------------------------

### Build Docker image on Windows (PowerShell)

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Executes the build-docker.ps1 script to build the Docker image on Windows using PowerShell.

```powershell
.uild-docker.ps1
```

--------------------------------

### Generate Color Ramp and Set Palette

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-effects.md

Generates a color ramp with specified steps and hue shift, then sets the Aseprite file's palette. Useful for creating custom gradients.

```python
# Or generate a ramp
ramp = await generate_color_ramp("#D04648", steps=8, hue_shift_degrees=20)
await set_palette("sprite.aseprite", json.loads(ramp))
```

--------------------------------

### Visual Feedback Loop for Drawing

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Essential for drawing sprites. Export frames frequently to preview changes and adjust your drawing based on visual feedback. Requires creating a canvas and adding layers before starting the iteration.

```python
await create_canvas(32, 32, "sprite.aseprite")
await add_layer("sprite.aseprite", "body")

# Iterate: draw → preview → adjust
for iteration in range(5):
    await draw_pixels_at("sprite.aseprite", "body", 1, new_pixels)
    await export_frame("sprite.aseprite", 1, "preview.png", scale=8)
    # Open preview.png to inspect
    # Adjust new_pixels based on visual feedback
```

--------------------------------

### Handle Frame Index Out of Range Error

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/errors.md

This snippet shows how to handle a 'Frame Index Out of Range' error. It includes an example of the error occurring and a recovery method using sprite information to validate the frame index.

```python
result = await set_frame("sprite.aseprite", 100)  # If sprite has only 8 frames
# Returns: "Failed to set frame: Frame index out of range"
```

```python
# Get sprite info to determine valid frame range
info = json.loads(await get_sprite_info("sprite.aseprite"))
max_frame = info["frames"]
if frame_index < 1 or frame_index > max_frame:
    print(f"Frame {frame_index} out of range (1-{max_frame})")
else:
    await set_frame("sprite.aseprite", frame_index)
```

--------------------------------

### Run container with inline environment variables

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Runs the Aseprite MCP container passing Steam credentials directly via environment variables. Not recommended for security.

```powershell
# Or pass inline (not recommended for security)
docker run --rm -i -e STEAM_USERNAME=you -e STEAM_PASSWORD=secret aseprite-mcp:latest
```

--------------------------------

### Check Aseprite Availability via Python

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Verifies if the Aseprite executable is accessible in the system's PATH or via the `ASEPRITE_PATH` environment variable. Prints the version or an error message.

```python
import subprocess
import os

aseprite = os.getenv('ASEPRITE_PATH', 'aseprite')
try:
    result = subprocess.run([aseprite, "--version"], capture_output=True, text=True)
    print(f"Aseprite version: {result.stdout}")
except FileNotFoundError:
    print(f"Error: Aseprite not found at {aseprite}")
```

--------------------------------

### Draw Pixels on Specific Layer and Frame

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-drawing.md

Plots pixels on a specific layer and frame within an Aseprite file. Optionally creates the layer and cel if they do not exist. Pixel data format is the same as `draw_pixels`, and frame indices start at 1.

```python
async def draw_pixels_at(
    filename: str,
    layer_name: str,
    frame_index: int,
    pixels: List[Dict[str, Any]],
    create_if_missing: bool = True
) -> str:
    # Function implementation omitted for brevity
```

```python
await draw_pixels_at("sprite.aseprite", "body", 2, [
    {"x": 10, "y": 10, "color": "#FF0000"}
])
```

--------------------------------

### Run Aseprite MCP with Docker Compose

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Deploy Aseprite MCP using Docker Compose for production or development. The development profile enables hot-reloading.

```bash
# Production
docker-compose up aseprite-mcp
```

```bash
# Development mode
docker-compose --profile dev up aseprite-mcp-dev
```

--------------------------------

### Python Project Metadata in pyproject.toml

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Specify project name, version, Python requirements, and dependencies for the aseprite-mcp project.

```toml
[project]
name = "aseprite-mcp"
version = "0.1.0"
requires-python = ">=3.13"

[project.dependencies]
httpx = ">=0.28.1"
mcp = { version = ">=1.6.0", extras = ["cli"] }

[dependency-groups]
dev = ["pytest>=9.0.3"]
```

--------------------------------

### Get Color Statistics for a Frame

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Analyzes a specific frame in an Aseprite file to report color usage statistics. Helps in checking palette discipline by identifying the most frequent colors and their counts. Returns a JSON object with unique color count, opaque pixel count, and top colors.

```python
async def get_color_stats(filename: str, frame_index: int = 1, top: int = 16) -> str:
    # Function implementation details omitted for brevity
    pass
```

--------------------------------

### Check File Existence

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/errors.md

Before proceeding with operations, verify that the target file exists on the filesystem.

```python
os.path.exists(filename)
```

--------------------------------

### Generate and Set Color Ramp Palette

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-palette.md

Generates a color ramp from a base color and then sets this ramp as the palette for an Aseprite file. Useful for creating custom gradients.

```python
# Or generate from a base color
ramp_json = await generate_color_ramp("#8B4513", steps=8)
ramp = json.loads(ramp_json)
await set_palette("sprite.aseprite", ramp)
```

--------------------------------

### Layer Path Resolution (Lua)

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-canvas.md

Demonstrates how layer names with '/' separators are resolved. The algorithm prioritizes exact matches, then uses longest-prefix matching for group paths. This allows for both nested layers and layers with literal '/' characters in their names.

```lua
-- FIND_LAYER Lua snippet
-- Tries an exact full-name match first (breadth-first, so shallower layers win)
-- If the name contains "/", parses it as a "group/child" path with longest-prefix-first matching
-- Allows "/" within actual layer names while still supporting group paths
```

--------------------------------

### Batch Operations vs. Looping in Aseprite-MCP

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Use single operations on ranges for better performance instead of looping and launching a new process for each frame.

```python
await tween_cel_positions("sprite.aseprite", "body", 1, 8, ...)
```

```python
for frame in range(1, 9):
    await set_cel_position("sprite.aseprite", "body", frame, ...)
```

--------------------------------

### Performance Tip: Minimize Format Conversions

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Avoid unnecessary format conversions. Once a palette or color mode is set, subsequent operations will use it, reducing redundant calls.

```python
# Good
await apply_palette_preset("sprite.aseprite", "pico8")
# All subsequent draws use pico8

# Less efficient
await apply_palette_preset("sprite.aseprite", "pico8")
await set_color_mode("sprite.aseprite", "rgb")
await apply_palette_preset("sprite.aseprite", "pico8")
```

--------------------------------

### Docker Compose Usage

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER_SETUP_SUMMARY.md

Commands to manage the Aseprite MCP container using Docker Compose for production and development environments.

```bash
# Production
docker-compose up aseprite-mcp
```

```bash
# Development
docker-compose --profile dev up aseprite-mcp-dev
```

--------------------------------

### Performance Tip: Use Range Operations

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Prefer range operations over individual loop iterations for operations like tweening cel positions to minimize process launches.

```python
# Good
await tween_cel_positions("sprite.aseprite", "body", 1, 8, ...)

# Slow (8 process launches)
for frame in range(1, 9):
    await set_cel_position("sprite.aseprite", "body", frame, ...)
```

--------------------------------

### apply_palette_preset

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-palette.md

Applies a predefined color palette preset to an Aseprite file. This is useful for quickly setting up a consistent color scheme.

```APIDOC
## apply_palette_preset

### Description
Applies a predefined color palette preset to an Aseprite file.

### Method Signature
```python
await apply_palette_preset("sprite.aseprite", "pico8")
```

### Parameters
- **filename** (str) - Required - The path to the Aseprite file.
- **preset_name** (str) - Required - The name of the palette preset to apply (e.g., "pico8").
```

--------------------------------

### Make build script executable

Source: https://github.com/diivi/aseprite-mcp/blob/main/DOCKER.md

Ensures the build-docker.sh script has execute permissions on Linux/macOS.

```bash
chmod +x build-docker.sh
```

--------------------------------

### Animation with Tweening and Onion Skinning

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Facilitates animation creation by setting up frames, tweening cel positions with easing, and rendering onion skins for visual reference. Finally, it exports the animation as a GIF.

```python
# Set up frames
await add_frames("sprite.aseprite", 8, duration_ms=100)

# Tween motion
await tween_cel_positions_eased(
    "sprite.aseprite", "body", 1, 8,
    start_x=0, start_y=0,
    end_x=16, end_y=0,
    easing="ease_in_out"
)

# Check motion
await render_onion_skin("sprite.aseprite", 4, "onion.png", before=2, after=2, scale=8)

# Export animation
await export_tag("sprite.aseprite", "default", "animation.gif")
```

--------------------------------

### Apply Palette Preset

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/configuration.md

Minimize format conversions by applying a palette preset once. All subsequent operations will use this palette.

```python
await apply_palette_preset("sprite.aseprite", "pico8")
```

--------------------------------

### Create, Add, Duplicate, and Reference Layers in Groups

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-layers.md

Demonstrates creating a new group, adding a layer to that group, duplicating a layer into a group, and setting the visibility of a layer within a nested group structure. These operations are essential for organizing complex sprite assets.

```python
# Create a group
await add_group("sprite.aseprite", "character")

# Add a layer to the group
await add_layer("sprite.aseprite", "body", group="character")

# Duplicate a layer into a group
await duplicate_layer("sprite.aseprite", "arms", new_name="arms_shadow", group="character")

# Reference a layer deep in a group
await set_layer_visibility("sprite.aseprite", "character/body", visible=False)
```

--------------------------------

### list_slices

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-other.md

Lists all slices in an Aseprite file, including their bounds, 9-patch centers, and pivots.

```APIDOC
## list_slices

### Description
List all slices with their bounds, 9-patch centers, and pivots.

### Method
```python
async def list_slices(filename: str) -> str
```

### Returns
JSON array of slice objects
```

--------------------------------

### Set Environment Variables using .env File

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

Define environment variables, such as `ASEPRITE_PATH`, within a `.env` file located in the project root. This provides a convenient way to manage configuration for Aseprite batch operations.

```dotenv
ASEPRITE_PATH=/path/to/aseprite
```

--------------------------------

### Quantize to Palette

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-effects.md

Snaps colors within a specified layer and frame range to the current palette. This is the final step to ensure palette consistency after applying effects.

```python
await quantize_to_palette("sprite.aseprite", layer_name="body", start_frame=1, end_frame=4)
```

--------------------------------

### Palette-Driven Workflow for Sprite Creation

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/README.md

This workflow emphasizes establishing a color palette first, then drawing using those colors, and finally snapping imported images to the established palette. It ensures color consistency across your sprites.

```python
# 1. Establish palette first
await apply_palette_preset("sprite.aseprite", "pico8")

# 2. Draw using palette colors
palette = json.loads(await get_palette("sprite.aseprite"))
skin_color = palette[5]
await draw_pixels_at("sprite.aseprite", "body", 1, [
    {"x": 10, "y": 10, "color": skin_color}
])

# 3. Snap imported content to palette
await import_image_as_layer("sprite.aseprite", "ref.png", "reference")
await quantize_to_palette("sprite.aseprite", layer_name="reference")
```

--------------------------------

### Create New Aseprite Canvas

Source: https://github.com/diivi/aseprite-mcp/blob/main/_autodocs/api-reference-canvas.md

Use this function to create a new Aseprite sprite with specified dimensions and an output filename. Ensure width and height are greater than 0.

```python
async def create_canvas(width: int, height: int, filename: str = "canvas.aseprite") -> str:
    # ... function body ...
    pass

await create_canvas(32, 32, "sprite.aseprite")
# Returns: "Canvas created successfully: sprite.aseprite"
```