Skip to main content
Glama
ayigityol

aseprite-mcp

by ayigityol
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Local

aseprite-mcp

An MCP server for Aseprite — create, edit, and export pixel art sprites, animations, and sprite sheets from any AI assistant.

Drawn and animated entirely via aseprite-mcp tools — no manual pixel editing!

Features

  • 43 tools across 11 categories

  • Native drawing with configurable brush thickness via app.useTool()

  • Pixel-perfect algorithms (Bresenham line, midpoint circle) for thin strokes

  • Cross-platform — Windows, macOS, Linux

  • Secure — Lua injection prevention, sandboxed execution

  • Zero runtime dependencies beyond @modelcontextprotocol/sdk

Tool Overview

Category

Tools

Examples

Sprites

6

create_sprite, resize_sprite, crop_sprite

Layers

4

add_layer, set_layer_properties, list_layers

Frames

4

add_frame, set_frame_duration, list_frames

Tags

3

create_tag, remove_tag, list_tags

Drawing

7

draw_rect, draw_circle, draw_line, draw_ellipse, fill_area, outline, draw_pixels

Transform

5

replace_color, flip_sprite, rotate_sprite, flatten_layers, merge_down

Palette

4

get_palette, set_palette_colors, load_palette, resize_palette

Cels

3

move_cel, set_cel_opacity, clear_cel

Export

3

export_sprite_sheet, export_frame, export_layers

Slices

2

create_slice, remove_slice

Utility

2

run_script, get_aseprite_version

📖 Full parameter reference: docs/API.md

Related MCP server: LibreSprite MCP

Quick Start

Requirements

Install

# npm global
npm install -g aseprite-mcp

# or from source
git clone https://github.com/ayigityol/aseprite-mcp.git
cd aseprite-mcp && npm install && npm run build

Configure

{
  "mcpServers": {
    "aseprite": {
      "type": "local",
      "command": "node",
      "tools": ["*"],
      "args": ["/path/to/aseprite-mcp/build/index.js"],
      "env": { "ASEPRITE_PATH": "/path/to/aseprite" }
    }
  }
}
{
  "mcpServers": {
    "aseprite": {
      "command": "node",
      "args": ["/path/to/aseprite-mcp/build/index.js"],
      "env": { "ASEPRITE_PATH": "/path/to/aseprite" }
    }
  }
}
{
  "servers": {
    "aseprite": {
      "command": "node",
      "args": ["/path/to/aseprite-mcp/build/index.js"],
      "env": { "ASEPRITE_PATH": "/path/to/aseprite" }
    }
  }
}
{
  "mcpServers": {
    "aseprite": {
      "command": "aseprite-mcp"
    }
  }
}

Environment Variables

Variable

Description

ASEPRITE_PATH

Path to Aseprite executable. Auto-detected if not set.

DEBUG

Set "true" for verbose stderr logging.

Auto-detection searches standard install paths on all platforms, plus system PATH.

Architecture

sequenceDiagram
    participant Client as MCP Client
    participant Server as aseprite-mcp
    participant Aseprite as Aseprite CLI

    Client->>Server: Tool call (JSON-RPC via stdio)
    Server->>Server: Generate Lua script
    Server->>Aseprite: aseprite -b --script temp.lua
    Aseprite->>Aseprite: Execute Lua (headless)
    Aseprite-->>Server: stdout: __RESULT__{"success":true, ...}
    Server->>Server: Parse JSON, cleanup temp file
    Server-->>Client: Tool result
graph LR
    A[Tool Call] --> B{Thickness > 1?}
    B -->|Yes| C[app.useTool<br/>Native Brush]
    B -->|No| D[image:drawPixel<br/>Pixel Algorithms]
    C --> E[Save & Return]
    D --> E

All operations run headless — no GUI window is opened.

Docker

# Build
docker build -t aseprite-mcp .

# Run (mount your Aseprite binary + working directory)
docker run --rm -i \
  -v /path/to/aseprite:/usr/local/bin/aseprite:ro \
  -v ./sprites:/sprites \
  aseprite-mcp

# Or use Docker Compose
docker compose up

Aseprite must be mounted into the container. The image packages only the MCP server.

Development

npm run build       # Compile TypeScript
npm run watch       # Recompile on changes
npm test            # Run 74 unit tests (vitest)
npm run test:watch  # Watch mode
npm run inspector   # MCP Inspector for interactive testing

Security

  • luaEscape() — prevents Lua injection by escaping \, ", \n, \r

  • luaPath() — normalizes and escapes file paths

  • execFile() — argument arrays, no shell interpolation

  • pcall() wrapping — all generated Lua scripts have error handlers

  • Local only — no data sent to external services

Troubleshooting

Problem

Solution

"Aseprite executable not found"

Set ASEPRITE_PATH env var to the full path

Tool returns Aseprite error

Set DEBUG=true to see stderr output

"Layer not found" / "Tag not found"

Names are case-sensitive — use list_layers or list_tags first

Sprite won't save

Ensure the output directory exists

License

MIT

Install Server
A
license - permissive license
B
quality
D
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ayigityol/aseprite-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server