Skip to content
Back to search

pixel-mcp

MCP server for creating pixel art with Aseprite through AI assistants. Supports animation, retro palettes, dithering, shading, and spritesheet export.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/willibrandon--pixel-mcp/badge.svg)](/listings/willibrandon--pixel-mcp)

HTML

<a href="/listings/willibrandon--pixel-mcp"><img src="/api/listings/willibrandon--pixel-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install

# Clone the repository
git clone https://github.com/willibrandon/pixel-mcp.git
cd pixel-mcp

# Build the server
make build

2. Configure

Create `~/.config/pixel-mcp/config.json`:

{
  "aseprite_path": "/path/to/aseprite",
  "temp_dir": "/tmp/pixel-mcp",
  "timeout": 30,
  "log_level": "info",
  "log_file": "",
  "enable_timing": false
}

**Configuration options:** - `aseprite_path` (required): Absolute path to Aseprite executable. No automatic discovery or environment variables. - `temp_dir` (optional): Directory for temporary files. Defaults to `/tmp/pixel-mcp`. - `timeout` (optional): Command timeout in seconds. Defaults to 30. - `log_level` (optional): Logging verbosity (`debug`, `info`, `warn`, `error`). Defaults to `info`. - `log_file` (optional): Path to log file for persistent logging. If empty, logs only to stderr. - `enable_timing` (optional): Enable request tracking and operation timing. Defaults to `false`.

3. Run

# Run the server (stdio transport)
./bin/pixel-mcp

# Check health
./bin/pixel-mcp --health

# Enable debug logging
./bin/pixel-mcp --debug

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 262 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Aseprite MCP Server
  2. A 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.
  3. ![Showcase Pixel Art](docs/images/showcase-pixel-art-4x.png)
  4. *Example scene created using pixel-mcp: 64x64 indexed sprite with custom 16-color palette, demonstrating drawing primitives (rectangles, circles) and palette management.*
  5. ## Features
  6. - **Canvas & Layer Management:** RGB, Grayscale, and Indexed color modes with multi-layer support and layer deletion
  7. - **Drawing Primitives:** Pixels, lines, rectangles, circles, polylines, flood fill with batch operations and palette-aware drawing
  8. - **Selection Tools:** Rectangle, ellipse, select all, copy, cut, paste, move selections with multiple blend modes (replace/add/subtract/intersect)
  9. - **Professional Pixel Art Tools:**
  10. - **Reference Analysis:** Extract palettes, brightness maps, edge detection, and composition guides from images
  11. - **Color Quantization:** Reduce images to 2-256 colors using median_cut, k-means, or octree algorithms with optional Floyd-Steinberg dithering
  12. - **Automatic Shading:** Apply geometry-based shading with 3 styles (cell/smooth/soft), 8 light directions, and adjustable intensity
  13. - **Dithering:** 16 patterns including Bayer matrices (2x2, 4x4, 8x8), Floyd-Steinberg, checkerboard, and textures (grass, water, stone, cloud, brick, dots, diagonal, cross, noise, lines)
  14. - **Palette Management:** Set custom palettes (1-256 colors), sort by hue/luminance, analyze color harmonies (complementary/triadic/analogous), and extract from reference images
  15. - **Shading Tools:** Apply palette-constrained shading with smooth, hard, or pillow styles and 8 light directions
  16. - **Antialiasing:** Detect jagged diagonal edges and suggest intermediate colors for smoother curves (manual or auto-apply)
  17. - **Transform Operations:** Flip, rotate, scale, crop, resize canvas, apply outlines, and downsample for pixel art conversion
  18. - **Palette-Aware Drawing:** All drawing tools support snapping to nearest palette color using LAB color space
  19. - **Animation Tools:** Frame durations, tags, frame duplication/deletion, linked cels
  20. - **Inspection Tools:** Read pixel data with pagination for verification and analysis
  21. - **Export Formats:** PNG, GIF, JPG, BMP, and spritesheet export (horizontal/vertical/grid layouts)
  22. - **Cross-platform:** Windows, macOS, Linux
  23. - **MCP Integration:** Works with Claude Desktop and other MCP clients
  24. ## Requirements
  25. - Go 1.23+
  26. - Aseprite 1.3.0+ (1.3.10+ recommended)
  27. ## Quick Start
  28. ### 1. Install
  29. ```bash
  30. # Clone the repository
  31. git clone https://github.com/willibrandon/pixel-mcp.git
  32. cd pixel-mcp
  33. # Build the server
  34. make build
  35. ```
  36. ### 2. Configure
  37. Create `~/.config/pixel-mcp/config.json`:
  38. ```json
  39. {
  40. "aseprite_path": "/path/to/aseprite",
  41. "temp_dir": "/tmp/pixel-mcp",
  42. "timeout": 30,
  43. "log_level": "info",
  44. "log_file": "",
  45. "enable_timing": false
  46. }
  47. ```
  48. **Configuration options:**
  49. - `aseprite_path` (required): Absolute path to Aseprite executable. No automatic discovery or environment variables.
  50. - `temp_dir` (optional): Directory for temporary files. Defaults to `/tmp/pixel-mcp`.
  51. - `timeout` (optional): Command timeout in seconds. Defaults to 30.
  52. - `log_level` (optional): Logging verbosity (`debug`, `info`, `warn`, `error`). Defaults to `info`.
  53. - `log_file` (optional): Path to log file for persistent logging. If empty, logs only to stderr.
  54. - `enable_timing` (optional): Enable request tracking and operation timing. Defaults to `false`.
  55. ### 3. Run
  56. ```bash
  57. # Run the server (stdio transport)
  58. ./bin/pixel-mcp
  59. # Check health
  60. ./bin/pixel-mcp --health
  61. # Enable debug logging
  62. ./bin/pixel-mcp --debug
  63. ```
  64. ## Usage with Claude Desktop
  65. Add to your Claude Desktop config:
  66. ```json
  67. {
  68. "mcpServers": {
  69. "aseprite": {
  70. "command": "/absolute/path/to/pixel-mcp"
  71. }
  72. }
  73. }
  74. ```
  75. Then use natural language to create sprites:
  76. - "Create a 64x64 sprite and draw a red circle in the center"
  77. - "Add a new layer called 'Background' and fill it with blue"
  78. - "Export the sprite as a PNG"
  79. ## Available Tools
  80. ### Canvas & Layer Management
  81. | Tool | Description |
  82. |------|-------------|
  83. | `create_canvas` | Create new sprite with specified dimensions and color mode |
  84. | `add_layer` | Add a new layer to the sprite |
  85. | `delete_layer` | Delete a layer from the sprite (cannot delete last layer) |
  86. | `flatten_layers` | Flatten all layers in a sprite into a single layer |
  87. | `get_sprite_info` | Get sprite metadata (size, layers, frames) |
  88. ### Drawing & Painting
  89. | Tool | Description |
  90. |------|-------------|
  91. | `draw_pixels` | Draw individual pixels (supports batch operations, optional palette snapping) |
  92. | `draw_line` | Draw a line between two points (optional palette snapping) |
  93. | `draw_contour` | Draw a polyline or polygon by connecting multiple points (optional palette snapping) |
  94. | `draw_rectangle` | Draw a rectangle (filled or outline, optional palette snapping) |
  95. | `draw_circle` | Draw a circle/ellipse (filled or outline, optional palette snapping) |
  96. | `fill_area` | Flood fill from a point (paint bucket, optional palette snapping) |
  97. ### Selection & Clipboard
  98. | Tool | Description |
  99. |------|-------------|
  100. | `select_rectangle` | Create a rectangular selection with mode (replace/add/subtract/intersect) |
  101. | `select_ellipse` | Create an elliptical selection with mode (replace/add/subtract/intersect) |
  102. | `select_all` | Select the entire canvas |
  103. | `deselect` | Clear the current selection |
  104. | `move_selection` | Move selection bounds by offset (does not move pixels) |
  105. | `cut_selection` | Cut selected pixels to clipboard |
  106. | `copy_selection` | Copy selected pixels to clipboard |
  107. | `paste_clipboard` | Paste clipboard content at specified position |
  108. **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.
  109. ### Professional Pixel Art
  110. | Tool | Description |
  111. |------|-------------|
  112. | `analyze_reference` | Extract palette, brightness map, edges, and composition from reference images |
  113. | `draw_with_dither` | Fill region with dithering patterns (15 patterns: Bayer, checkerboard, grass, water, stone, cloud, brick, etc.) |
  114. | `downsample_image` | Downsample high-res images to pixel art dimensions using box filter |
  115. | `get_palette` | Retrieve current sprite palette as array of hex colors with size |
  116. | `set_palette` | Set sprite's color palette to specified colors (supports 1-256 colors) |
  117. | `set_palette_color` | Set a specific palette index to a color (0-255) |
  118. | `add_palette_color` | Add a new color to the palette (max 256 colors) |
  119. | `sort_palette` | Sort palette by hue, saturation, brightness, or luminance (ascending/descending) |
  120. | `apply_shading` | Apply palette-constrained shading based on light direction (smooth, hard, or pillow styles) |
  121. | `analyze_palette_harmonies` | Analyze palette for complementary, triadic, analogous relationships and color temperature |
  122. | `suggest_antialiasing` | Detect jagged diagonal edges and suggest intermediate colors for smooth curves (with optional auto-apply) |
  123. ### Transform & Filter
  124. | Tool | Description |
  125. |------|-------------|
  126. | `flip_sprite` | Flip sprite, layer, or cel horizontally or vertically |
  127. | `rotate_sprite` | Rotate sprite, layer, or cel by 90, 180, or 270 degrees |
  128. | `scale_sprite` | Scale sprite with algorithm selection (nearest, bilinear, rotsprite) |
  129. | `crop_sprite` | Crop sprite to rectangular region |
  130. | `resize_canvas` | Resize canvas without scaling content (with anchor positioning) |
  131. | `apply_outline` | Apply outline effect to layer with configurable color and thickness |
  132. ### Animation
  133. | Tool | Description |
  134. |------|-------------|
  135. | `add_frame` | Add a new animation frame |
  136. | `delete_frame` | Delete a frame from the sprite (cannot delete last frame) |
  137. | `set_frame_duration` | Set the duration of an animation frame in milliseconds |
  138. | `create_tag` | Create an animation tag with playback direction |
  139. | `delete_tag` | Delete an animation tag by name |
  140. | `duplicate_frame` | Duplicate an existing frame with all cels |
  141. | `link_cel` | Create a linked cel that shares image data |
  142. ### Inspection & Export
  143. | Tool | Description |
  144. |------|-------------|
  145. | `get_pixels` | Read pixel data from a rectangular region (paginated, for verification) |
  146. | `export_sprite` | Export sprite to PNG/GIF/JPG/BMP |
  147. | `export_spritesheet` | Export animation frames as spritesheet (horizontal/vertical/rows/columns/packed layout, optional JSON metadata) |
  148. | `import_image` | Import external image file as a layer in the sprite |
  149. | `save_as` | Save sprite to a new .aseprite file path |
  150. ## Examples
  151. See [examples/](examples/) for a complete working example client that demonstrates all features including canvas creation, animation, dithering, palette management, shading, and antialiasing.
  152. ## Development
  153. ### Using Make
  154. ```bash
  155. # Build (development - fast, no version info)
  156. make build
  157. # Build release (with version and timestamp)
  158. make release
  159. # Run unit tests
  160. make test
  161. # Run unit tests (no cache)
  162. make test-nocache
  163. # Run integration tests (requires configured Aseprite)
  164. make test-integration
  165. # Run integration tests (no cache)
  166. make test-integration-nocache
  167. # Run benchmarks
  168. make bench
  169. # Run linters
  170. make lint
  171. # Generate coverage report
  172. make test-coverage
  173. # Clean build artifacts
  174. make clean
  175. ```
  176. ### Using Go CLI
  177. ```bash
  178. # Build (development)
  179. go build -o bin/pixel-mcp ./cmd/pixel-mcp
  180. # Build release (with version info)
  181. go build -ldflags "-X main.Version=$(git describe --tags --always --dirty) -X main.BuildTime=$(date -u '+%Y-%m-%d_%H:%M:%S')" -o bin/pixel-mcp ./cmd/pixel-mcp
  182. # Run unit tests
  183. go test -v -race -cover ./...
  184. # Run unit tests (no cache)
  185. go test -v -race -cover -count=1 ./...
  186. # Run integration tests
  187. go test -tags=integration -v ./...
  188. # Run integration tests (no cache)
  189. go test -tags=integration -v -count=1 ./...
  190. # Run benchmarks
  191. go test -tags=integration -bench=. -benchmem ./pkg/aseprite ./pkg/tools
  192. # Run linters
  193. go vet ./...
  194. go fmt ./...
  195. # Generate coverage report
  196. go test -v -race -coverprofile=coverage.txt -covermode=atomic ./...
  197. go tool cover -html=coverage.txt -o coverage.html
  198. ```
  199. ## Performance
  200. All 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.
  201. ## License
  202. [MIT](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.