aseprite-mcp
Shexiaoyun/aseprite-mcp
Aseprite MCP Server - AI-assisted pixel art creation via Aseprite native Lua extension
Instalação
npx convez-ai Shexiaoyun/aseprite-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.
Aseprite MCP Server
AI-assisted pixel art creation for Aseprite via the Model Context Protocol (MCP).
Connect your favorite AI client (Claude, Cursor, DeepChat, etc.) directly to Aseprite. Draw, erase, fill, and manipulate your sprites using natural language instructions.
📐 Architecture
┌─────────────────────┐ stdio (MCP) ┌──────────────────────────┐
│ AI Client │ ◄──────────────────► │ MCP Server (Node.js) │
│ Claude / Cursor │ │ • Tool Registration │
│ / DeepChat / ... │ │ • Request Routing │
└─────────────────────┘ │ • WebSocket Bridge │
└──────────┬───────────────┘
│ WebSocket
┌──────────▼───────────────┐
│ Aseprite Extension │
│ (Lua + WebSocket) │
│ • Command Gateway │
│ • Tool Dispatcher │
│ • app.useTool() API │
└──────────────────────────┘
Why this direction?
Aseprite's WebSocket() API can only act as a client connecting to a URL. It cannot listen on a port. Therefore, the MCP Server must host the WebSocket Server, and the Aseprite extension connects to it.
Communication Flow
- AI Client sends a
use_toolrequest via MCP stdio to the MCP Server - MCP Server validates parameters, generates a
request_id, and sends anAsepriteRequestover WebSocket - Aseprite Extension receives the request, routes to the appropriate tool handler, and calls
app.useTool() - Aseprite Extension returns a tri-state response (
completed/failed/rejected) with the samerequest_id - MCP Server matches the response to the pending Promise and maps it to an MCP
CallToolResult - AI Client receives the result (success or detailed error)
🛠 Technology Stack
| Layer | Technology | Purpose |
|---|---|---|
| AI ↔ MCP | @modelcontextprotocol/sdk | MCP protocol implementation over stdio |
| MCP Server | TypeScript / Node.js | Tool registration, validation, request routing |
| WebSocket Bridge | ws (npm) | WebSocket Server, heartbeat, request-timeout matching |
| Protocol | JSON (AsepriteRequest / AsepriteResponse) | Tri-state response model |
| Aseprite Extension | Lua (Aseprite API v25+) | WebSocket client, command gateway, tool dispatch |
| Tool Implementation | Lua (app.useTool()) | Pixel-level drawing operations |
Key Design Decisions
- No external JSON library: Aseprite v1.3-rc5+ has built-in
json.encode()/json.decode() - No
uuidpackage: Node.js 19+ providescrypto.randomUUID()natively - Modular Lua architecture: Gateway dispatcher in
mcp-bridge.lua, individual tools intools/*.lualoaded viarequire() - Dual timeout strategy: WebSocket ping/pong heartbeat (30s) + per-request timeout (30s)
- Zero-throw error propagation: All errors flow through Promise resolve/reject as structured
AsepriteResponse
🚀 Getting Started
Prerequisites
- Aseprite: v1.3-rc5 or later (
app.apiVersion >= 25) - Node.js: v18 or later
- AI Client: Claude Desktop, Cursor, DeepChat, or any MCP-compatible client
Step 1: Install the MCP Server
git clone https://github.com/your-org/aseprite-mcp.git
cd aseprite-mcp
npm install
npm run build
Step 2: Install the Aseprite Extension
- Locate the
aseprite-extension/folder in this repository - Compress the folder contents into a
.zipfile - Rename the
.zipto.aseprite-extension - Double-click the
.aseprite-extensionfile, or install via:
Aseprite → Edit → Preferences → Extensions → Add Extension - Ensure the MCP Bridge extension is checked/enabled
- Restart Aseprite
After restarting, open the Aseprite console (F1) and confirm:
[MCP Bridge] [INFO] MCP Bridge v0.1 initializing...
[MCP Bridge] [INFO] Connected to MCP Server at ws://127.0.0.1:9876
Step 3: Configure Your AI Client
DeepChat
{
"mcpServers": {
"aseprite": {
"name": "aseprite-mcp",
"transport": "stdio",
"command": "node",
"args": [
"C:\\path\\to\\aseprite-mcp\\dist\\index.js"
],
"env": {
"ASE_MCP_PORT": "9876"
}
}
}
}
Claude Desktop
%APPDATA%\Claude\settings.json:
{
"mcpServers": {
"aseprite": {
"command": "node",
"args": ["C:\\path\\to\\aseprite-mcp\\dist\\index.js"],
"env": { "ASE_MCP_PORT": "9876" }
}
}
}
Cursor
Settings → MCP → Add Server:
{
"mcpServers": [
{
"name": "aseprite",
"type": "stdio",
"command": "node",
"args": ["C:\\path\\to\\aseprite-mcp\\dist\\index.js"]
}
]
}
Generic (MCP stdio-compatible)
{
"command": "node",
"args": ["/path/to/aseprite-mcp/dist/index.js"],
"env": { "ASE_MCP_PORT": "9876" }
}
Port Configuration: Default WebSocket port is
9876. Override with--portCLI argument orASE_MCP_PORTenvironment variable.
🎨 Example Prompts
Once connected, ask your AI to draw:
Draw a red pixel at (10, 10) using the pencil tool.
Erase the area from (5, 5) to (15, 15).
Fill the region around (20, 20) with blue color.
Draw a line from (0, 0) to (50, 50) in green.
📁 Project Structure
aseprite-mcp/
├── src/ # TypeScript source
│ ├── index.ts # Entry point (bridge + MCP server)
│ ├── mcp-server.ts # MCP Server & tool registration
│ ├── ws-bridge.ts # WebSocket Server & request matching
│ ├── protocol.ts # Message protocol types
│ ├── tools-proto.ts # Tool type definitions
│ └── tools/
│ └── use-tool.ts # use_tool MCP schema + handler
├── aseprite-extension/ # Aseprite Extension (Lua)
│ ├── package.json # Extension manifest
│ ├── mcp-bridge.lua # WebSocket client + command gateway
│ └── tools/
│ └── use-tool.lua # use_tool command processor
├── dist/ # Compiled JavaScript output
├── package.json # Node.js project config
└── tsconfig.json # TypeScript config
🧪 Development
# Build
npm run build
# Run
npm start
# Dev mode (build + run)
npm run dev
# Tests
npm test
# Watch mode
npm run watch
📄 License
MIT License. See LICENSE for details.