Aseprite

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

📖 Full parameter reference: docs/API.md

Quick Start

Requirements

• Node.js ≥ 18
• Aseprite ≥ 1.3 (aseprite.org)

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

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

License

MIT