pixel-mcp

pixel-mcp

An MCP (Model Context Protocol) server that lets AI coding agents (Claude Code, Cursor, Windsurf, etc.) create pixel art programmatically. No daemon, no sockets, no Go runtime — just a lightweight TypeScript server that runs via npx.

Install

Use with Claude Code

Run this from your project directory:

claude mcp add pixel-art npx -- pxcli-mcp --export-dir ./assets/sprites

This registers the server in Claude Code's config scoped to your project. Verify it's connected with /mcp.

Use with any MCP client

npx pxcli-mcp --export-dir ./output

From source

npm install
npm run build
node dist/index.js --export-dir ./output

Quick start

Once configured, Claude (or any MCP client) can use these tools directly:

create_canvas(name: "hero", width: 16, height: 16)
fill_rect(canvas: "hero", x: 0, y: 0, width: 16, height: 16, color: "black")
set_pixel(canvas: "hero", x: 8, y: 4, color: "#ff0000")
draw_line(canvas: "hero", x1: 0, y1: 15, x2: 15, y2: 15, color: "white")
export_png(canvas: "hero", filename: "hero.png")

Tools

| Tool | Description | |------|-------------| | create_canvas | Create a named canvas with given dimensions (max 256x256) | | list_canvases | List all active canvases and their sizes | | set_pixel | Set a single pixel color | | get_pixel | Read a pixel's color | | fill_rect | Fill a rectangle with a solid color | | draw_line | Draw a line between two points (Bresenham's algorithm) | | clear | Clear entire canvas to a color (default: transparent) | | export_png | Export canvas to a PNG file | | undo | Undo the last drawing operation | | redo | Redo the last undone operation |

All drawing tools accept a canvas parameter (defaults to "default"), so you can work on multiple sprites simultaneously.

Color formats

• Hex: #rgb, #rrggbb, #rrggbbaa
• Named: red, green, blue, white, black, transparent, yellow, cyan, magenta, orange, purple, gray, grey, pink, brown, lime, navy, teal, maroon, olive

CLI options

| Flag | Description | |------|-------------| | --export-dir <path> | Directory for exported PNGs (defaults to CWD) |

Playground (live preview)

The repo includes viewer.html — a browser-based playground for watching pixel art being drawn in real time.

1. Serve the file locally:

   npx serve .

1. Open http://localhost:3000/viewer.html in your browser

The playground has two columns:

• Left: Scaled pixel canvas with coordinate tracker on hover
• Right: Prompt field, canvas settings (name, dimensions, scale, background, export dir), action buttons, and a live operation log

The canvas exposes global drawing functions (px, rect, line) that can be called from the browser console or via browser automation tools (e.g. Claude in Chrome). This makes it easy to visually verify pixel art as it's being drawn step by step.

Drawing from the browser console

// Set a red pixel at (10, 5)
px(10, 5, 255, 0, 0, 255)

// Fill a blue rectangle
rect(0, 0, 16, 16, 0, 0, 255, 255)

// Draw a green line
line(0, 0, 15, 15, 0, 255, 0, 255)

// Update status message
setStatus('Drawing complete!')

Development

npm install
npm run build
npm test        # runs 22 tests (unit + MCP integration)
npm run dev     # watch mode for TypeScript compilation

Credits

Inspired by and built on top of vossenwout/pixel-art-cli — thank you for the original Go daemon-based pixel art CLI that made this possible.