Content
<div align="center">
# Tool List
**Let AI Create Pixel Art in Aseprite**
An MCP (Model Context Protocol) server that enables AI to create pixel art in Aseprite through pixel-level drawing primitives, reading canvas screenshots, and iterative refinement until a satisfactory artwork is achieved.
[](https://www.python.org/)
[](https://github.com/jlowin/fastmcp)
[](https://aseprite.org/)
[](https://github.com/ZhangDongyang800/Aseprite_MCP/stargazers)
<p align="center">
<a href="README_EN.md">🇺🇸 English</a>
</p>
</div>
<br>
> [!IMPORTANT]
> This project requires local installation of [Aseprite](https://aseprite.org/) v1.3+, and AI uses MCP protocol to call Aseprite CLI + Lua script to complete drawing.
---
## How to Use
### 1. Environment Preparation
Before configuring MCP, you need to prepare the local development environment:
| Dependency | Version Requirement | Download |
|------|---------|------|
| Python | 3.10+ | [python.org](https://www.python.org/downloads/) |
| Aseprite | v1.3+ | [aseprite.org](https://aseprite.org/) (remember the installation path) |
### 2. MCP Server Setup
```bash
git clone https://github.com/ZhangDongyang800/Aseprite_MCP.git
cd Aseprite_MCP
pip install fastmcp
```
### 3. Client Configuration
> [!IMPORTANT]
> The following configurations need to be replaced with your local actual paths:
> - `args` path of `server.py`
> - `ASEPRITE_PATH` environment variable value
> - `command` path of `python`
**TRAE:**
Open TRAE → Settings → MCP → Add MCP Server, paste:
```json
{
"mcpServers": {
"aseprite": {
"command": "python",
"args": ["C:\\path\\to\\Aseprite_MCP\\server.py"],
"env": {
"ASEPRITE_PATH": "C:\\Program Files\\Aseprite\\aseprite.exe"
}
}
}
}
```
**Codex CLI:**
Configuration file: `~/.codex/config.toml`
```toml
[mcp_servers.aseprite]
command = "python"
args = ["/path/to/Aseprite_MCP/server.py"]
[mcp_servers.aseprite.env]
ASEPRITE_PATH = "C:\\Program Files\\Aseprite\\aseprite.exe"
```
After configuration, let AI use Aseprite-related tools to start creating.
---
## What Can It Do
Let AI create pixel art in Aseprite like human artists - supports pixel-level drawing, multi-layer management, animation frame editing, color palette control, animation tags, image transformation, canvas preview, and a complete workflow with **48 tools**.
### Pixel-Level Drawing
All drawing tools support `layer` and `frame` parameters, allowing drawing on specified layers and frames (default: layer 1, frame 1).
| Tool | Description |
|------|------|
| `draw_pixel` | Draw a pixel at specified coordinates |
| `draw_line` | Draw a line |
| `draw_rect` | Draw a rectangle (supports hollow/solid) |
| `draw_ellipse` | Draw an ellipse (supports hollow/solid) |
| `fill_region` | Paint bucket fill connected area |
| `clear_region` | Clear specified area to transparent |
| `clear_canvas` | Clear entire canvas |
### Sprite Management
| Tool | Description |
|------|------|
| `create_sprite` | Create a new canvas (supports `rgb` / `grayscale` / `indexed` mode) |
| `open_sprite` | Open an existing `.ase` or `.png` file |
| `save_sprite` | Save as `.ase` / `.png` / `.gif` |
| `close_session` | Close session and clean up temporary resources |
### Animation and Frames
| Tool | Description |
|------|------|
| `add_frame` | Add a new frame (copy previous frame or create a blank frame) |
| `remove_frame` | Delete a specified frame |
| `set_frame_duration` | Set frame duration (seconds) |
| `get_frame_info` | Get all frame information (frame count, frame duration) |
| `export_gif` | Export GIF animation (supports scaling) |
| `export_sprite_sheet` | Export sprite sheet (PNG + JSON data) |
### Layer Management
| Tool | Description |
|------|------|
| `add_layer` | Create a new layer |
| `remove_layer` | Delete a layer (by name or index) |
| `set_layer_properties` | Set layer properties (name, visibility, opacity, blend mode) |
| `get_layer_info` | Get all layer information |
| `move_cel` | Move cel between layers/frames |
### Color Palette
| Tool | Description |
|------|------|
| `set_palette_color` | Set the color of a specified index in the color palette |
| `get_palette` | Get the current color palette |
| `resize_palette` | Adjust the color palette size (number of colors) |
| `load_palette` | Load a color palette from a file (`.gpl` / `.pal` / `.png`) |
### Animation Tags
| Tool | Description |
|------|------|
| `add_tag` | Create an animation tag (supports playback direction, loop count) |
| `remove_tag` | Delete a tag by name |
| `get_tags` | Get all tag information |
### Image Transformation
| Tool | Description |
|------|------|
| `flip_canvas` | Flip the canvas (horizontal/vertical) |
| `resize_sprite` | Resize the sprite |
| `rotate_canvas` | Rotate the canvas (90° / 180° / 270°) |
| `crop_sprite` | Crop the sprite to a specified area |
| `invert_color` | Invert all colors |
| `replace_color` | Replace a specified color |
### Color Palette Enhancement
| Tool | Description |
|------|------|
| `apply_preset_palette` | ★Batch★ Apply built-in preset color palettes (db16/db32/aap64/nes/gameboy) |
| `derive_shading_palette` | Derive a three-order color palette from the main color (hue offset, default auto-application) |
| `append_palette_colors` | ★Batch★ Append multiple colors to the color palette |
### Animation Assistance
| Tool | Description |
|------|------|
| `apply_timing_preset` | ★Batch★ Batch set frame duration by animation type |
| `draw_animation_frames` | ★Batch★ Draw multiple frames of animation at once |
| `export_onion_skin_preview` | Onion skin overlay preview (previous/next frame comparison) |
### Tileset Tools
| Tool | Description |
|------|------|
| `create_tileset_canvas` | Create a tileset canvas and set grid |
| `export_tiled_preview` | Tiled splicing preview (check seams) |
### Quality Inspection
| Tool | Description |
|------|------|
| `export_silhouette` | Export pure black silhouette (silhouette test) |
| `check_canvas_standards` | Automatic canvas standard check (size/color/frame duration/pixel) |
### Canvas Inspection
| Tool | Description |
|------|------|
| `get_canvas_preview` | Export PNG image for AI visual analysis (**core iterative tool**) |
| `get_canvas_info` | Get canvas metadata (size, color mode, etc.) |
| `get_pixel_color` | Query the color value of a specified coordinate pixel |
### Other Capabilities
- **MCP Resources** — Session list, default color palette, canvas metadata, blend mode list, animation direction list
- **MCP Prompts** — Sprite creation guide, iterative review guide, animation creation guide, multi-layer workflow guide
> [!TIP]
> `get_canvas_preview` is the core of the entire workflow: AI calls it to "look" at the canvas after drawing, analyzes it, and decides whether to refine it, forming a **draw → preview → analyze → refine** loop.
<br>
<div align="center">
```
AI Request → MCP Tool Call → FastMCP (Python) → Aseprite CLI → Lua Script → .ase File
↓
AI Visual Analysis ← base64 PNG ← Image Object ← FastMCP ← export_png.lua ←─┘
```
</div>
---
## 🎮 Demo
The project includes a knight walking animation example, demonstrating how AI can create complete game assets through Aseprite MCP.
**Example: Chibi Knight Walk Cycle**
<div align="center">
**Four-Direction Walking Animation**
| ↓ Down | ↑ Up |
|:---:|:---:|
|  |  |
| ← Left | → Right |
|  |  |
**Sprite Sheet**
</div>
**AI Prompt:**
> Use Aseprite MCP to generate a pixel art sprite sheet showcasing a brave knight in silver armor, holding a long sword, walking in four directions (down, up, left, right), each direction with 4 frames of animation, 32x32 size, flat color, transparent background.
---
## 🤝 Contributions Welcome
Feel free to submit [Issues](https://github.com/ZhangDongyang800/Aseprite_MCP/issues) and [Pull Requests](https://github.com/ZhangDongyang800/Aseprite_MCP/pulls)!
I've tried it, but can't guarantee it's perfect; it still needs more optimization.
---
## License
This project is open-sourced under the [MIT License](LICENSE).
Copyright © 2026 [ZhangDongyang800](https://github.com/ZhangDongyang800)
<div align="center">
<sub>Built with ❤️ for pixel art lovers</sub>
</div>
