Pixelsmith

A pixel-art sprite editor your AI agent can actually drive. Headless core, browser editor, MCP server — all rendering the same pixels.

Status: 0.1, prototype. The engine and the MCP server are solid and well tested — 256 tests across the three packages. The hand-drawing tools are thin next to Aseprite. Read What this is and isn't before you invest in it.

Not published to npm yet. The npx commands below are how it will be installed; until then, clone the repo and run the server from packages/mcp/dist/server.js.

---

What it does

Connect an agent over MCP and it can create a sprite, draw into it, animate it with keyframes or procedural motion styles, and export a GIF, APNG or packed spritesheet — seeing a PNG preview after every single step. That last part is the whole design: an agent that can look at its own output iterates dramatically better than one working blind.

Drop a reference photo in the editor and the agent can read the actual pixels through an MCP resource, so "make it look like this" has something real behind it.

60-second quickstart

npx pixelsmith-mcp

That starts the MCP server on stdio with a sandboxed workspace in ./pixelsmith-workspace. Point a client at it.

Until the package is published, run it from a clone instead:

git clone https://github.com/liamlz11/pixelsmith
cd pixelsmith
npm install
npm run build
node packages/mcp/dist/server.js

The client configs below then take "command": "node" and "args": ["/absolute/path/to/pixelsmith/packages/mcp/dist/server.js"].

Claude Code

claude mcp add pixelsmith -- npx -y pixelsmith-mcp

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "pixelsmith": {
      "command": "npx",
      "args": ["-y", "pixelsmith-mcp"],
      "env": { "PIXELSMITH_WORKSPACE": "/absolute/path/to/a/folder" }
    }
  }
}

Cursor — .cursor/mcp.json:

{
  "mcpServers": {
    "pixelsmith": { "command": "npx", "args": ["-y", "pixelsmith-mcp"] }
  }
}

Cline — in cline_mcp_settings.json:

{
  "mcpServers": {
    "pixelsmith": { "command": "npx", "args": ["-y", "pixelsmith-mcp"], "disabled": false }
  }
}

Any generic MCP client — command npx, args ["-y", "pixelsmith-mcp"], transport stdio.

Then ask for something:

Create a 32×32 knight sprite, give it a breathing idle, and export a GIF.

The editor

git clone https://github.com/liamlz11/pixelsmith
cd pixelsmith
npm install
npm run dev

Opens on http://localhost:5173. On Windows, double-clicking dev.bat does the same thing — it installs dependencies on first run, builds the core package, starts the server and opens a browser. It shares the MCP server's library when both are running, so you can watch an agent draw and take over with the mouse mid-sprite.

Tool reference

Tool	What it does
list_characters, get_character	Browse the library
create_character, duplicate_character	Make sprites
set_pixels, draw_shape, import_item	Draw
add_layer, edit_layer, reorder_layers, merge_layers, add_layer_group, set_layer_blend	Structure
add_frame, set_frame_pixels, retime_frame, add_tag, set_tag_direction	Timeline
resize_canvas	Grow, pad or crop the canvas — the fix for artwork clipped in exports
add_transform_keyframe, apply_motion_style, bake_modifiers	Animation
apply_palette, add_swatch, add_ramp	Colour
add_reference, list_references, get_reference, update_reference, remove_reference	References
render_preview, export, export_spritesheet	Output
undo_character, redo_character, save_character	History

Resources: pixelsmith://project, pixelsmith://project/{id}, pixelsmith://project/{id}/reference/{refId}, pixelsmith://items.

Prompts: recreate-reference-as-sprite.

Every create/draw/transform/export tool returns a base64 PNG alongside its text.

Motion styles

breathe · bob · sway · walk · recoil · swing · float · pulse · shake

Each generates a transform track from a handful of numbers (amplitude, frequency, phase, easing). They stack with per-modifier weight, stay re-editable in the document, and bake down to plain keyframes when you want to hand-tune. shake runs off a seeded PRNG — the same seed always produces the same jitter, because nothing here may break determinism.

Configuration

Variable	Default	Purpose
PIXELSMITH_WORKSPACE	./pixelsmith-workspace	The only place on disk the server touches
PIXELSMITH_LIBRARY_DIR	<workspace>/library	Where documents are stored
PIXELSMITH_OUTPUT_DIR	<workspace>/output	Where exports are written
PIXELSMITH_INPUT_DIR	<workspace>/input	The only directory reference images may be read from
PIXELSMITH_EXAMPLES	unset	Path to an example pack JSON to preload
PIXELSMITH_MAX_CANVAS	512	Max canvas edge, in pixels
PIXELSMITH_MAX_CELLS	262144	Max total canvas cells
PIXELSMITH_MAX_FRAMES	256	Max frames per document
PIXELSMITH_MAX_LAYERS	64	Max layers per document
PIXELSMITH_MAX_DOC_BYTES	33554432	Max document size on disk
PIXELSMITH_MAX_CALLS_PER_MIN	600	Tool-call rate limit

Architecture

Three packages, one idea:

packages/core     headless. no DOM, no React. document model, compositor,
                  animation engine, encoders. this is the product.
packages/editor   browser UI. imports core.
packages/mcp      MCP server. imports the same core.

The editor and the MCP server never reimplement anything. A determinism test renders a document through the GUI path and the export path and asserts the RGBA buffers are byte-identical — that guarantee is why an agent can trust what it sees in a preview. See docs/architecture.md.

Examples

examples/ holds runnable agent scripts and one optional sample content pack:

• examples/scripts/generate-from-description.mjs — a character from a text prompt
• examples/scripts/walk-cycle-from-one-frame.mjs — animate a single drawing
• examples/scripts/batch-recolor.mjs — one sprite, N palettes
• examples/cyberlab-mentors/ — eleven example characters and a wardrobe of items cut out of them. Sample content, not part of the tool. Load with PIXELSMITH_EXAMPLES=examples/cyberlab-mentors/pack.json.

What this is and isn't

It is: a genuinely headless pixel-art engine with a well-shaped MCP surface. Deterministic. Every mutation returns a picture. References give a vision model real pixels to match. Animation is transform tracks and procedural motion, not a flipbook. Old documents keep opening — there are four schema versions and migrators for all of them.

It isn't: an Aseprite replacement. There are no linked cels, no free-transform, no tilemaps, no brush engine to speak of. Undo is per-document and in-memory. The editor is one dark theme with no customisation. If you want to draw pixel art by hand, buy Aseprite — it costs about as much as lunch and it is excellent.

Use it if you want an agent to make sprites, or you want a headless sprite engine to build on. Don't use it if you want a better mouse-driven drawing app.

Contributing

See CONTRIBUTING.md. Security issues: SECURITY.md.

Licence

MIT — see LICENSE.