# Aseprite Mcp

> MCP server for Aseprite — 43 tools for pixel art, animations, and sprite sheets.

- **Type:** MCP server
- **Install:** `agentstack add mcp-ayigityol-aseprite-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ayigityol](https://agentstack.voostack.com/s/ayigityol)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ayigityol](https://github.com/ayigityol)
- **Source:** https://github.com/ayigityol/aseprite-mcp

## Install

```sh
agentstack add mcp-ayigityol-aseprite-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# aseprite-mcp

An [MCP](https://modelcontextprotocol.io/) server for [Aseprite](https://www.aseprite.org/) — 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](docs/API.md)**

---

## Quick Start

### Requirements

- **Node.js** ≥ 18
- **Aseprite** ≥ 1.3 ([aseprite.org](https://www.aseprite.org/))

### Install

```bash
# 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

GitHub Copilot CLI (~/.copilot/mcp-config.json)

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

Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "aseprite": {
      "command": "node",
      "args": ["/path/to/aseprite-mcp/build/index.js"],
      "env": { "ASEPRITE_PATH": "/path/to/aseprite" }
    }
  }
}
```

VS Code / Cursor (.vscode/mcp.json)

```json
{
  "servers": {
    "aseprite": {
      "command": "node",
      "args": ["/path/to/aseprite-mcp/build/index.js"],
      "env": { "ASEPRITE_PATH": "/path/to/aseprite" }
    }
  }
}
```

Installed globally via npm

```json
{
  "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

```mermaid
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
```

```mermaid
graph LR
    A[Tool Call] --> B{Thickness > 1?}
    B -->|Yes| C[app.useToolNative Brush]
    B -->|No| D[image:drawPixelPixel Algorithms]
    C --> E[Save & Return]
    D --> E
```

All operations run **headless** — no GUI window is opened.

---

## Docker

```bash
# 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

```bash
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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ayigityol](https://github.com/ayigityol)
- **Source:** [ayigityol/aseprite-mcp](https://github.com/ayigityol/aseprite-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ayigityol-aseprite-mcp
- Seller: https://agentstack.voostack.com/s/ayigityol
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.