Aseprite MCP Tools v2.0

日本語版はこちら | macOS Setup Guide

A powerful Python MCP (Model Context Protocol) server for programmatic interaction with Aseprite, featuring enhanced error handling, configuration management, batch processing, and more!

🚀 What's New in v2.0

🛡️ Comprehensive Error Handling: Custom exceptions with detailed, actionable error messages
🔧 Configuration Management: Pydantic-based settings with JSON/YAML support
📝 Advanced Logging: Structured logging with performance metrics
🎨 Palette Management: Create, apply, and extract color palettes
⚡ Batch Processing: Process multiple files in parallel
🏗️ Lua Script Builder: Clean, type-safe Lua script generation
🔒 Enhanced Security: Input validation and path traversal protection
🧪 Full Test Coverage: Comprehensive unit tests

Related MCP server: MCP Builder

📋 Features

Core Drawing Tools

Canvas Operations: Create sprites, add layers and frames
Drawing Tools: Pixels, lines, rectangles, circles, and fill operations
Export Tools: Export to various formats with scaling and layer support

New Palette Tools (v2.0)

Preset Palettes: GameBoy, NES, PICO-8, CGA, Monochrome, Sepia
Custom Palettes: Create and apply custom color schemes
Palette Extraction: Extract colors from existing images
Color Remapping: Replace colors throughout sprites

Batch Processing (v2.0)

Batch Resize: Resize multiple sprites maintaining aspect ratio
Batch Export: Convert multiple files to different formats
Batch Palette Apply: Apply palettes to multiple files
Custom Scripts: Run Lua scripts on file sets

🔧 Installation

Requirements

Python 3.13+
Aseprite (must be installed separately)

Claude Desktop Configuration

Using UV (Recommended)

{ "mcpServers": { "aseprite": { "command": "/opt/homebrew/bin/uv", "args": [ "--directory", "/path/to/aseprite-mcp", "run", "-m", "aseprite_mcp" ], "env": { "ASEPRITE_PATH": "/path/to/aseprite" } } } }

Using Python

{ "mcpServers": { "aseprite": { "command": "python", "args": ["-m", "aseprite_mcp"], "cwd": "/path/to/aseprite-mcp", "env": { "ASEPRITE_PATH": "/path/to/aseprite" } } } }

Install Dependencies

pip install -r requirements.txt

⚙️ Configuration

Environment Variables

export ASEPRITE_PATH="/Applications/Aseprite.app/Contents/MacOS/aseprite" export ASEPRITE_MCP_LOG_LEVEL="INFO"

Configuration File (config.json)

{ "aseprite_path": "/path/to/aseprite", "canvas": { "max_width": 10000, "max_height": 10000 }, "batch": { "max_parallel_jobs": 4, "continue_on_error": true }, "log_level": "INFO", "security": { "allowed_directories": ["/home/user/sprites"], "max_file_size": 104857600 } }

Configuration File (config.yaml)

aseprite_path: /path/to/aseprite canvas: max_width: 10000 max_height: 10000 default_color_mode: RGBA batch: max_parallel_jobs: 4 continue_on_error: true log_level: INFO security: allowed_directories: - /home/user/sprites max_file_size: 104857600

📖 Usage Examples

Basic Drawing Operations

# Create a new sprite await create_canvas(320, 240, "my_sprite.aseprite") # Draw pixels await draw_pixels("my_sprite.aseprite", [ {"x": 10, "y": 10, "color": "FF0000"}, # Red {"x": 11, "y": 10, "color": "00FF00"}, # Green {"x": 12, "y": 10, "color": "0000FF"} # Blue ]) # Draw shapes await draw_rectangle("my_sprite.aseprite", 50, 50, 100, 80, "FFFF00", fill=True) await draw_circle("my_sprite.aseprite", 160, 120, 30, "FF00FF", fill=False) await draw_line("my_sprite.aseprite", 0, 0, 320, 240, "FFFFFF", thickness=2) # Fill area await fill_area("my_sprite.aseprite", 100, 100, "00FFFF", tolerance=10)

Layer and Frame Management

# Add a new layer await add_layer("my_sprite.aseprite", "Background") # Add animation frames await add_frame("my_sprite.aseprite", after_frame=0)

Palette Operations

# Apply preset palette await apply_preset_palette("my_sprite.aseprite", "gameboy") # Available presets: gameboy, gameboy-pocket, nes, pico-8, cga, monochrome, sepia # Create custom palette await create_palette("my_sprite.aseprite", [ "264653", "2A9D8F", "E9C46A", "F4A261", "E76F51" ]) # Extract palette from image await extract_palette_from_image("reference.png", max_colors=16) # Get palette information await get_palette_info("my_sprite.aseprite") # Remap colors await remap_colors("my_sprite.aseprite", { "FF0000": "00FF00", # Red to Green "0000FF": "FFFF00" # Blue to Yellow })

Export Operations

# Export single file await export_sprite("my_sprite.aseprite", "output.png", scale=2.0) # Export with frame range await export_sprite("animation.aseprite", "frames.gif", frame_range="1-10") # Export each layer separately await export_layers("my_sprite.aseprite", "layers/", format="png")

Batch Processing

# Resize multiple sprites await batch_resize( input_dir="sprites/", output_dir="sprites_small/", scale=0.5, file_pattern="*.aseprite" ) # Export batch to PNG await batch_export( input_dir="sprites/", output_dir="exports/", format="png", scale=2.0 ) # Apply palette to multiple files await batch_apply_palette( input_dir="sprites/", palette_file="my_palette.aseprite", create_backup=True ) # Run custom Lua script on multiple files await batch_process_custom( input_dir="sprites/", lua_script="app.activeSprite:flatten()", output_dir="flattened/" )

🏗️ Architecture

Project Structure

aseprite-mcp/ ├── aseprite_mcp/ │ ├── core/ │ │ ├── commands.py # Aseprite command execution │ │ ├── config.py # Configuration management │ │ ├── exceptions.py # Custom exceptions │ │ ├── logging.py # Logging system │ │ ├── lua_builder.py # Lua script builder │ │ └── validation.py # Input validation │ └── tools/ │ ├── batch.py # Batch processing │ ├── canvas.py # Canvas operations │ ├── drawing.py # Drawing tools │ ├── export.py # Export functions │ └── palette.py # Palette management ├── tests/ # Unit tests ├── examples/ # Example scripts └── config.example.yaml # Configuration example

Error Handling

try: result = await create_canvas(-100, 200, "test.aseprite") except ValidationError as e: print(f"Validation failed: {e}") except AsepriteError as e: print(f"Aseprite error: {e}")

Lua Script Builder

from aseprite_mcp.core.lua_builder import LuaBuilder builder = LuaBuilder() builder.create_sprite(200, 200) builder.begin_transaction() builder.set_color("FF0000") builder.for_loop("i", 0, 10) builder.draw_pixel("i * 10", "i * 10") builder.end_loop() builder.end_transaction() builder.save_sprite("output.aseprite") script = builder.build() # Returns clean Lua code

🧪 Testing

Run all tests:

pytest tests/ -v

Run specific test:

pytest tests/test_validation.py -v

Run demo script:

python examples/demo_improvements.py

📝 Logging

Logs include:

Operation tracking
Performance metrics
Error details with context
Structured JSON output (optional)

Example log:

2024-06-11 10:30:45 - aseprite_mcp - INFO - Operation: create_canvas 2024-06-11 10:30:45 - aseprite_mcp - INFO - Canvas created successfully 2024-06-11 10:30:45 - aseprite_mcp - INFO - Performance: create_canvas took 0.234s

🤝 Contributing

Fork the repository
Create a feature branch
Follow the coding standards:
- Use type hints
- Add input validation
- Include error handling
- Write unit tests
- Update documentation
Submit a pull request

📄 License

MIT License - see LICENSE file for details

🙏 Credits

Original implementation: Divyansh Singh
v2.0 improvements: Enhanced error handling, configuration, batch processing, and more

Aseprite MCP Tools