{"id":31773692,"url":"https://github.com/willibrandon/aseprite-mcp","last_synced_at":"2025-10-10T04:27:24.305Z","repository":{"id":317974548,"uuid":"1066885937","full_name":"willibrandon/aseprite-mcp","owner":"willibrandon","description":"Aseprite MCP server for AI-driven sprite creation","archived":false,"fork":false,"pushed_at":"2025-10-04T07:21:20.000Z","size":1429,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-04T09:18:17.074Z","etag":null,"topics":["aseprite","game-development","golang","lua-scripting","mcp-server","pixel-art","sprite-animation"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/willibrandon.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-30T05:13:41.000Z","updated_at":"2025-10-04T07:23:25.000Z","dependencies_parsed_at":"2025-10-04T09:18:24.553Z","dependency_job_id":"18cee61c-7391-492e-84f5-dca40fa7a8fb","html_url":"https://github.com/willibrandon/aseprite-mcp","commit_stats":null,"previous_names":["willibrandon/aseprite-mcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/willibrandon/aseprite-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2Faseprite-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2Faseprite-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2Faseprite-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2Faseprite-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willibrandon","download_url":"https://codeload.github.com/willibrandon/aseprite-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willibrandon%2Faseprite-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279002686,"owners_count":26083442,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aseprite","game-development","golang","lua-scripting","mcp-server","pixel-art","sprite-animation"],"created_at":"2025-10-10T04:27:21.418Z","updated_at":"2025-10-10T04:27:24.294Z","avatar_url":"https://github.com/willibrandon.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aseprite MCP Server\n\nA Model Context Protocol (MCP) server that exposes Aseprite's pixel art and animation capabilities to AI assistants, enabling you to create and edit sprites using natural language.\n\n## Features\n\n- **Canvas \u0026 Layer Management:** RGB, Grayscale, and Indexed color modes with multi-layer support and layer deletion\n- **Drawing Primitives:** Pixels, lines, rectangles, circles, polylines, flood fill with batch operations and palette-aware drawing\n- **Selection Tools:** Rectangle, ellipse, select all, copy, cut, paste, move selections with multiple blend modes (replace/add/subtract/intersect)\n- **Professional Pixel Art Tools:**\n  - **Reference Analysis:** Extract palettes, brightness maps, edge detection, and composition guides from images\n  - **Dithering:** 15 patterns including Bayer matrices (2x2, 4x4, 8x8), checkerboard, and textures (grass, water, stone, cloud, brick, dots, diagonal, cross, noise, lines)\n  - **Palette Management:** Set custom palettes (1-256 colors), sort by hue/luminance, analyze color harmonies (complementary/triadic/analogous), and extract from reference images\n  - **Shading Tools:** Apply palette-constrained shading with smooth, hard, or pillow styles and 8 light directions\n  - **Antialiasing:** Detect jagged diagonal edges and suggest intermediate colors for smoother curves (manual or auto-apply)\n  - **Transform Operations:** Flip, rotate, scale, crop, resize canvas, apply outlines, and downsample for pixel art conversion\n  - **Palette-Aware Drawing:** All drawing tools support snapping to nearest palette color using LAB color space\n- **Animation Tools:** Frame durations, tags, frame duplication/deletion, linked cels\n- **Inspection Tools:** Read pixel data with pagination for verification and analysis\n- **Export Formats:** PNG, GIF, JPG, BMP, and spritesheet export (horizontal/vertical/grid layouts)\n- **Cross-platform:** Windows, macOS, Linux\n- **MCP Integration:** Works with Claude Desktop and other MCP clients\n\n## Requirements\n\n- Go 1.23+\n- Aseprite 1.3.0+ (1.3.10+ recommended)\n\n## Quick Start\n\n### 1. Install\n\n```bash\n# Clone the repository\ngit clone https://github.com/willibrandon/aseprite-mcp.git\ncd aseprite-mcp\n\n# Build the server\nmake build\n```\n\n### 2. Configure\n\nCreate `~/.config/aseprite-mcp/config.json`:\n\n```json\n{\n  \"aseprite_path\": \"/path/to/aseprite\",\n  \"temp_dir\": \"/tmp/aseprite-mcp\",\n  \"timeout\": 30,\n  \"log_level\": \"info\",\n  \"log_file\": \"\",\n  \"enable_timing\": false\n}\n```\n\n**Configuration options:**\n- `aseprite_path` (required): Absolute path to Aseprite executable. No automatic discovery or environment variables.\n- `temp_dir` (optional): Directory for temporary files. Defaults to `/tmp/aseprite-mcp`.\n- `timeout` (optional): Command timeout in seconds. Defaults to 30.\n- `log_level` (optional): Logging verbosity (`debug`, `info`, `warn`, `error`). Defaults to `info`.\n- `log_file` (optional): Path to log file for persistent logging. If empty, logs only to stderr.\n- `enable_timing` (optional): Enable request tracking and operation timing. Defaults to `false`.\n\n### 3. Run\n\n```bash\n# Run the server (stdio transport)\n./bin/aseprite-mcp\n\n# Check health\n./bin/aseprite-mcp --health\n\n# Enable debug logging\n./bin/aseprite-mcp --debug\n```\n\n## Usage with Claude Desktop\n\nAdd to your Claude Desktop config:\n\n```json\n{\n  \"mcpServers\": {\n    \"aseprite\": {\n      \"command\": \"/absolute/path/to/aseprite-mcp\"\n    }\n  }\n}\n```\n\nThen use natural language to create sprites:\n- \"Create a 64x64 sprite and draw a red circle in the center\"\n- \"Add a new layer called 'Background' and fill it with blue\"\n- \"Export the sprite as a PNG\"\n\n## Available Tools\n\n### Canvas \u0026 Layer Management\n| Tool | Description |\n|------|-------------|\n| `create_canvas` | Create new sprite with specified dimensions and color mode |\n| `add_layer` | Add a new layer to the sprite |\n| `delete_layer` | Delete a layer from the sprite (cannot delete last layer) |\n| `get_sprite_info` | Get sprite metadata (size, layers, frames) |\n\n### Drawing \u0026 Painting\n| Tool | Description |\n|------|-------------|\n| `draw_pixels` | Draw individual pixels (supports batch operations, optional palette snapping) |\n| `draw_line` | Draw a line between two points (optional palette snapping) |\n| `draw_contour` | Draw a polyline or polygon by connecting multiple points (optional palette snapping) |\n| `draw_rectangle` | Draw a rectangle (filled or outline, optional palette snapping) |\n| `draw_circle` | Draw a circle/ellipse (filled or outline, optional palette snapping) |\n| `fill_area` | Flood fill from a point (paint bucket, optional palette snapping) |\n\n### Selection \u0026 Clipboard\n| Tool | Description |\n|------|-------------|\n| `select_rectangle` | Create a rectangular selection with mode (replace/add/subtract/intersect) |\n| `select_ellipse` | Create an elliptical selection with mode (replace/add/subtract/intersect) |\n| `select_all` | Select the entire canvas |\n| `deselect` | Clear the current selection |\n| `move_selection` | Move selection bounds by offset (does not move pixels) |\n| `cut_selection` | Cut selected pixels to clipboard |\n| `copy_selection` | Copy selected pixels to clipboard |\n| `paste_clipboard` | Paste clipboard content at specified position |\n\n**Note**: Selection and clipboard operations persist across MCP tool calls using sprite custom properties (`sprite.data`) and a hidden clipboard layer. This allows you to create a selection in one tool call, then copy/cut/paste in subsequent calls. Selection bounds are automatically saved and restored, and clipboard content is stored in a hidden `__mcp_clipboard__` layer.\n\n### Professional Pixel Art\n| Tool | Description |\n|------|-------------|\n| `analyze_reference` | Extract palette, brightness map, edges, and composition from reference images |\n| `draw_with_dither` | Fill region with dithering patterns (15 patterns: Bayer, checkerboard, grass, water, stone, cloud, brick, etc.) |\n| `downsample_image` | Downsample high-res images to pixel art dimensions using box filter |\n| `get_palette` | Retrieve current sprite palette as array of hex colors with size |\n| `set_palette` | Set sprite's color palette to specified colors (supports 1-256 colors) |\n| `set_palette_color` | Set a specific palette index to a color (0-255) |\n| `add_palette_color` | Add a new color to the palette (max 256 colors) |\n| `sort_palette` | Sort palette by hue, saturation, brightness, or luminance (ascending/descending) |\n| `apply_shading` | Apply palette-constrained shading based on light direction (smooth, hard, or pillow styles) |\n| `analyze_palette_harmonies` | Analyze palette for complementary, triadic, analogous relationships and color temperature |\n| `suggest_antialiasing` | Detect jagged diagonal edges and suggest intermediate colors for smooth curves (with optional auto-apply) |\n\n### Transform \u0026 Filter\n| Tool | Description |\n|------|-------------|\n| `flip_sprite` | Flip sprite, layer, or cel horizontally or vertically |\n| `rotate_sprite` | Rotate sprite, layer, or cel by 90, 180, or 270 degrees |\n| `scale_sprite` | Scale sprite with algorithm selection (nearest, bilinear, rotsprite) |\n| `crop_sprite` | Crop sprite to rectangular region |\n| `resize_canvas` | Resize canvas without scaling content (with anchor positioning) |\n| `apply_outline` | Apply outline effect to layer with configurable color and thickness |\n\n### Animation\n| Tool | Description |\n|------|-------------|\n| `add_frame` | Add a new animation frame |\n| `delete_frame` | Delete a frame from the sprite (cannot delete last frame) |\n| `set_frame_duration` | Set the duration of an animation frame in milliseconds |\n| `create_tag` | Create an animation tag with playback direction |\n| `delete_tag` | Delete an animation tag by name |\n| `duplicate_frame` | Duplicate an existing frame with all cels |\n| `link_cel` | Create a linked cel that shares image data |\n\n### Inspection \u0026 Export\n| Tool | Description |\n|------|-------------|\n| `get_pixels` | Read pixel data from a rectangular region (paginated, for verification) |\n| `export_sprite` | Export sprite to PNG/GIF/JPG/BMP |\n| `export_spritesheet` | Export animation frames as spritesheet (horizontal/vertical/rows/columns/packed layout, optional JSON metadata) |\n| `import_image` | Import external image file as a layer in the sprite |\n| `save_as` | Save sprite to a new .aseprite file path |\n\n## Examples\n\nSee [examples/](examples/) for a complete working example client that demonstrates all features including canvas creation, animation, dithering, palette management, shading, and antialiasing.\n\n## Development\n\n### Using Make\n\n```bash\n# Build (development - fast, no version info)\nmake build\n\n# Build release (with version and timestamp)\nmake release\n\n# Run unit tests\nmake test\n\n# Run unit tests (no cache)\nmake test-nocache\n\n# Run integration tests (requires configured Aseprite)\nmake test-integration\n\n# Run integration tests (no cache)\nmake test-integration-nocache\n\n# Run benchmarks\nmake bench\n\n# Run linters\nmake lint\n\n# Generate coverage report\nmake test-coverage\n\n# Clean build artifacts\nmake clean\n```\n\n### Using Go CLI\n\n```bash\n# Build (development)\ngo build -o bin/aseprite-mcp ./cmd/aseprite-mcp\n\n# Build release (with version info)\ngo build -ldflags \"-X main.Version=$(git describe --tags --always --dirty) -X main.BuildTime=$(date -u '+%Y-%m-%d_%H:%M:%S')\" -o bin/aseprite-mcp ./cmd/aseprite-mcp\n\n# Run unit tests\ngo test -v -race -cover ./...\n\n# Run unit tests (no cache)\ngo test -v -race -cover -count=1 ./...\n\n# Run integration tests\ngo test -tags=integration -v ./...\n\n# Run integration tests (no cache)\ngo test -tags=integration -v -count=1 ./...\n\n# Run benchmarks\ngo test -tags=integration -bench=. -benchmem ./pkg/aseprite ./pkg/tools\n\n# Run linters\ngo vet ./...\ngo fmt ./...\n\n# Generate coverage report\ngo test -v -race -coverprofile=coverage.txt -covermode=atomic ./...\ngo tool cover -html=coverage.txt -o coverage.html\n```\n\n## Performance\n\nAll operations complete in under 100ms on typical hardware, with complete workflows finishing in 280-840ms. See [docs/BENCHMARKS.md](docs/BENCHMARKS.md) for detailed benchmark results.\n\n## License\n\n[MIT](LICENSE)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillibrandon%2Faseprite-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwillibrandon%2Faseprite-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillibrandon%2Faseprite-mcp/lists"}