# diivi/aseprite-mcp [Health: Active]

**Category:** 🎥 Multimedia Process  
**Repository:** https://github.com/diivi/aseprite-mcp  
**GitHub Stars:** 1000  
**Views:** 12  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/diivi-aseprite-mcp

## Description
MCP server using the Aseprite API to create pixel art

## Tools
Capabilities this server exposes over MCP:

- **create_canvas** — Create a new sprite with the given dimensions
- **add_layer** — Add a new layer, optionally inside a named group
- **add_group** — Add a new (optionally nested) group layer
- **add_frame** — Append a new frame
- **set_frame** — Set the active frame
- **set_frame_duration** — Set one frame's duration in ms
- **set_layer** — Set the active layer (optionally creating it)
- **draw_pixels** — Plot individual pixels with per-pixel colors
- **draw_pixels_at** — Plot pixels on a specific layer/frame
- **draw_line** — Lines with thickness
- **draw_rectangle** — Outlined or filled rectangles
- **draw_circle** — Outlined or filled circles
- **draw_ellipse_at** — Outlined or filled ellipses with separate x/y radii
- **draw_polygon** — Outlined or filled polygons from a point list
- **draw_path** — Polyline through a point list with thickness
- **fill_area** — Paint-bucket flood fill
- **apply_gradient_rect** — Smooth linear gradient fill in a rectangle
- **draw_rows** — Pixels as rows of characters plus a colour legend, like ASCII art, with an optional 1px outline — the compact way to place hand-chosen detail (faces, hands, animals, handles)
- **draw_iso_box** — Solid 2:1 isometric box with clean 2-1 edges and a colour per face, for furniture and props
- **list_text_fonts** — List the bitmap and TrueType fonts available to `draw_text
- **measure_text** — Width, height, advance and baseline extents — size a panel or centre a label without redrawing to find out
- **draw_text** — Draw text with anchors, faux bold, outline, drop shadow and letter spacing
- **delete_layer** — Delete a layer by name
- **rename_layer** — Rename a layer
- **duplicate_layer** — Duplicate a layer with all cels, opacity, and blend mode, optionally into a group
- **reorder_layer** — Move a layer to a position in the stack
- **set_layer_blend_mode** — Set blend mode (multiply, screen, overlay, ... 19 modes)
- **merge_layer_down** — Merge a layer into the one below it
- **flatten_sprite** — Flatten all layers into one
- **move_region** — Cut a rectangle of pixels and paste it elsewhere
- **copy_region** — Copy a rectangle to another position, layer, or frame
- **erase_region** — Make a rectangle transparent
- **erase_color** — Magic-eraser: make all pixels of a color transparent (with tolerance)
- **outline_cel** — Add a 1px outline around all opaque pixels, or only around the shapes in a region
- **replace_color** — Replace one color with another (with tolerance), preserving alpha
- **adjust_hsl** — Shift hue/saturation/lightness of a cel — palette swaps, night scenes, shadows
- **apply_dither_gradient** — Two-color gradient using Bayer 4×4 ordered dithering
- **apply_dither_pattern** — Uniform dithered mix of two colors at a given density
- **outline_native** — Aseprite's Outline command around opaque pixels
- **adjust_hsl_native** — Aseprite's Hue/Saturation/Lightness filter
- **adjust_brightness_contrast** — Brightness/Contrast filter
- **invert_colors** — Colour inversion
- **apply_convolution** — Convolution filter: blur, sharpen, edge, emboss …
- **list_convolution_matrices** — List the built-in matrices for `apply_convolution
- **extract_palette** — Build an optimal palette from the sprite (native colour quantization)
- **add_frames** — Append N frames with optional duration
- **delete_frame** — Delete a frame
- **set_frame_duration_all** — Set every frame's duration
- **duplicate_frame_range** — Duplicate a frame range N times
- **copy_frame** — Copy all cels of a frame to other frames
- **create_cel** — Cel lifecycle on a layer/frame
- **propagate_cels** — Copy selected layers' cels across a frame range
- **set_cel_position** — Place a cel at x,y
- **set_cel_opacity** — Set a single cel's opacity
- **offset_cel_positions** — Shift cels by a delta across frames
- **tween_cel_positions** — Linear position tween across frames
- **tween_cel_positions_eased** — Position tween with easing (ease_in/out, smoothstep)
- **tween_cel_opacity_eased** — Opacity tween with easing
- **tween_cel_scale_eased** — Scale tween with easing and anchor
- **oscillate_cel_positions** — Sine-wave motion (bobbing, breathing, hovering)
- **set_tag** — Animation tags with direction (forward/reverse/pingpong)
- **set_layer_visibility** — Layer-level visibility and opacity
- **set_onion_skin** — Configure onion-skin UI prefs (see `render_onion_skin` for batch use)
- **get_sprite_info** — Sprite metadata: size, layers, frames, durations, tags
- **get_palette** — Read the palette as hex colors
- **set_palette** — Set the palette from a list of hex colors
- **list_palette_presets** — List built-in retro palettes
- **apply_palette_preset** — Apply a preset: `gameboy`, `pico8`, `c64`, `cga`, `dawnbringer16`, `dawnbringer32`, `grayscale_4`, `monochrome
- **generate_color_ramp** — Build a dark→light shading ramp with hue shifting from a base color
- **quantize_to_palette** — Snap every pixel to the nearest palette color
- **remap_colors_in_cel_range** — Remap specific colors across a frame range
- **set_color_mode** — Convert between RGB, grayscale, and indexed
- **flip_layer** — Flip a cel horizontally or vertically
- **rotate_layer** — Rotate a cel 90/180/270°
- **resize_canvas** — Scale the sprite to new dimensions
- **crop_canvas** — Crop to a rectangle
- **create_slice** — Create a named rectangular region
- **set_slice_center** — Set the 9-patch stretchable center
- **set_slice_pivot** — Set the pivot point
- **list_slices** — List all slices with bounds, centers, pivots as JSON

## Claude Desktop Quick Installation
No generated config for this server: it installs through its own setup steps.

The project's own setup steps (from https://github.com/diivi/aseprite-mcp), copied verbatim. Run them in order; they are not an mcpServers config.

1. Install:

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

2. Start the server:

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

3. Start the server:

```sh
docker-compose up aseprite-mcp
```

4. Start the server:

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

5. Start the server:

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

## Documentation

## What diivi/aseprite-mcp does

Aseprite becomes controllable through MCP with diivi/aseprite-mcp, a Python server intended for creating and editing pixel art and animated sprites. The repository describes 123 tools organized into 18 categories. These cover the sprite canvas, raster drawing, text, layers, regions, effects, animation, palettes, transforms, slices, tilemaps, import and export, inspection, analysis, quality checks, scene operations, previews, and scripting.

The server supports both construction and revision workflows. An agent can create a sprite, establish layers and frames, place pixels or geometric shapes, add text, adjust layer structure, and prepare an animation. Inspection and feedback tools let a workflow examine pixels, metadata, previews, frame differences, bounds, colors, and animation consistency.

## How it works

The MCP client sends tool calls to the Python server, which uses Aseprite’s API to operate on sprites. Canvas tools establish dimensions and active state; drawing tools then target the current or an explicitly selected layer and frame. Variants ending in `_at` can address a particular layer and frame directly, and can create the required cel when needed. Coordinates are expressed in sprite-global space.

For compact, hand-authored details, `draw_rows` accepts character rows plus a color legend. It can leave unmatched characters untouched and optionally add a one-pixel outline. `draw_iso_box` creates a solid 2:1 isometric box with separate colors for its faces, which is useful for props and furniture.

Animation work can append frames, select frames, assign durations, and use the broader animation and quality categories for frame-oriented workflows. Export tools cover formats and views such as PNG, GIF, sprite sheets, per-layer output, per-tag output, and previews on a background.

## Tools and capabilities

- Create sprites and manage layers, groups, active frames, and frame durations.
- Draw pixels, lines, rectangles, circles, ellipses, polygons, paths, gradients, and flood fills.
- Render compact pixel designs with character rows and construct isometric boxes.
- List fonts, measure text, and draw text with anchors, faux bold, outlines, shadows, and letter spacing.
- Duplicate, rename, reorder, merge, flatten, delete, and change the blend mode of layers.
- Work with palettes, effects, transforms, slices, tilemaps, animation data, and sprite regions.
- Inspect pixels and metadata, generate previews and onion-skin renders, compare frames, check bounds, and run lint or quality validation.
- Use a raw Lua tool for Aseprite operations not covered by the higher-level interface.

Text rendering is handled on the server because Aseprite’s Lua API does not provide text drawing. Bitmap sprite-sheet fonts and TrueType fonts are supported. Fonts can come from the server’s `~/.aseprite-mcp/fonts` directory, installed system fonts, or a direct font path.

## Limitations and notes

Text layout should generally begin with `measure_text`; it returns the dimensions and baseline information used by `draw_text`, allowing labels and panels to be positioned before rendering. Bitmap fonts are suited to pixel-art output because their glyphs are already rasterized and their size scales by whole numbers. TrueType files can be rendered without antialiasing unless antialiasing is requested.

The repository’s examples include still sprites, multi-frame animations, isometric scenes, and exported GIF or PNG results. The listed tool categories extend beyond the individual canvas and drawing operations, so the short tool list commonly shown in integrations represents only part of the complete interface.

_Full upstream README: https://allmcps.com/mcp/diivi-aseprite-mcp/readme_