pixel-mcp

An MCP server that lets an LLM create and edit pixel art reliably. Implements SPEC.md: indexed-color documents (8x8 to 256x256), layers, frames, symmetry, grid-text editing, server-side PNG/GIF rendering, reference quantization, and advisory quality linting.

Plain JavaScript with TypeScript-checked JSDoc types (tsc --checkJs, strict). No native dependencies.

Setup

pnpm install
pnpm check   # typecheck (tsc, strict, noEmit)
pnpm test    # node:test suite, includes an in-memory MCP end-to-end test
pnpm start   # run the server on stdio

Claude Desktop / Claude Code style config:

{
  "mcpServers": {
    "pixel": {
      "command": "node",
      "args": ["c:/path/to/pixel-mcp/src/index.js"]
    }
  }
}

Persistence

Documents survive restarts. Everything is written through to disk on every successful edit, and loaded on boot:

<dataDir>/
  documents/<docId>/
    document.json    # size, palette, layers, frames, symmetry, tile mode, stamps, selections
    cels/<frame>__<layer>.bin   # raw palette-index buffers
    preview.png      # composited frame 0, human-viewable
  refs/<refId>.png   # loaded reference images

dataDir defaults to the platform data directory (%LOCALAPPDATA%\pixel-mcp on Windows, ~/Library/Application Support/pixel-mcp on macOS, $XDG_DATA_HOME/pixel-mcp elsewhere). Override with --data-dir <path> or PIXEL_MCP_DATA_DIR. Undo/redo stacks and checkpoints are in-memory only, like a normal editor.

PIXEL_MCP_EXPORT_SCALE sets the default export scale factor for the project (built-in 4). Set it to 1 for native-resolution delivery — game textures an engine samples want no upscaling — so the model needn't pass scale on every export. A per-call scale argument still overrides it.

Tool surface (~60 tools)

• Lifecycle — create_document, open_document (PNG import + quantize), export (png / gif / aseprite_json — writes a real file to a caller path or <dataDir>/exports/ and returns the path; return_base64 for the bytes; default scale from PIXEL_MCP_EXPORT_SCALE), resize_canvas, undo, redo, describe, list_documents, delete_document, set_symmetry, set_tile_mode, set_active_layer, set_active_frame, checkpoint
• Palette — set_palette_color, add_palette_color, remove_palette_color (remaps pixels), swap_palette_indices, generate_ramp (cool shadows / warm highlights), replace_color, mix_palette_colors (blend two entries into a third), adjust_palette_color (HSL nudge in place or as a new variant), extract_palette (median-cut a PNG into hex colors + a swatch, no document — feeds create_document)
• Drawing — set_pixels, line (pixel-perfect no_doubles), rect, ellipse, flood_fill, outline, paste_grid
• Shading & texture — shade (ramp-step or nearest-snap darken/lighten), dither_gradient (ordered-dither blend between two indices), scatter (seeded grain/noise from an index set), import_image (drop an external PNG onto a layer or store it as a stamp)
• Regions — copy_region / cut_region (named stamps), paste_stamp (flip/rotate; ignores symmetry by default so placed content is never silently mirror-corrupted), move_region, mirror_region, shift_layer, clear_region, save_selection
• Layers — add_layer, remove_layer, rename_layer, reorder_layer, set_layer_visibility, set_layer_lock, merge_down
• Viewing — view, view_text, view_diff (vs. checkpoint), view_window (zoomed patch + context thumbnail), view_tiled (NxN repeat with seams marked — the perception tool for seamless textures)
• References — load_reference, quantize_reference, view_reference
• Animation — add_frame, remove_frame, reorder_frame, set_frame_duration, copy_cel, view_frames (onion skin; the model's perception tool for motion), preview_gif (human-facing output — clients show a GIF as a single still in model context)
• Lint — lint with all ten spec rules (orphans, doubles, banding, pillow_shading, unused_colors, near_duplicates, broken_outline, symmetry_drift, stray_alpha, tile_seams) plus persistent waivers via lint_waive / lint_unwaive: judged-and-accepted findings stay suppressed on every later pass. doubles flags rhythm breaks in diagonal staircases, not every 2-over-1 step, so ellipses don't light up; symmetry_drift reports one finding per contiguous asymmetric region; tile_seams only fires when a tile mode is set, so ordinary sprites stay quiet.

Every editing tool returns the changed bounding box plus a render of the changed region (4px context) and a whole-canvas thumbnail; pass render: false to skip. All edits are atomic — a failed call leaves the document untouched — and undoable (depth 100).

Grid text

One character per pixel, one line per row: . = transparent, 1-9 map to palette indices 1-9, a-z to 10-35, A-Z to 36-61, # = 62, @ = 63. (0 parses as transparent.) Digit characters equal their palette index, matching the spec's example; the spec's prose lists one more character than there are slots, which this resolves.

grid 8x8 palette=4
.111111.
11111111
11211211
11111111
12111121
11222211
11111111
.111111.
legend: 1=yellow #f8e030  2=black #202020

Workflow tip that earned its place in live testing: for a planned sequence of edits, pass render: false on each call and batch-verify with view at milestones. Use view_text for pixel-exact ground truth and view for gestalt — the two channels together are the point.

Spec deviations and gap-fills

• set_symmetry, set_active_frame, save_selection, list_documents, delete_document are added; the spec references the underlying state but defines no tool to manage it.
• open_document and load_reference accept PNG only; Aseprite binary import is not implemented (export to Aseprite JSON is).
• quantize_reference with palette: 'auto' appends the extracted colors to the document palette so the returned indices are immediately valid.
• Persistence (not in the spec) as described above.

Development

Manual end-to-end smoke that writes renders to scripts/smoke-out/ for eyeballing: node scripts/smoke.mjs.