Skip to content
HHpetraPublic

About

让 AI 通过 MCP 精确绘制像素画的本地工具。 A local tool that allows AI to precisely draw pixel art via MCP

Resources

Contributing

Stars

14 stars

Watchers

0 watching

Forks

Repository files navigation

PixelDraw

English | 简体中文

A local MCP server that lets AI draw pixel art through explicit coordinates and constrained MARD palettes, rather than text-to-image generation.

Rust executes the drawing commands; your MCP client supplies the model. PixelDraw itself needs no API key and exposes no network listener.

What it does

PixelDraw gives an AI assistant a small drawing workspace. You describe what to draw in your MCP client; the assistant creates a canvas and draws with lines, rectangles, triangles, circles, ellipses, diamonds, curves, flood fill, a full-canvas background fill, or pixel stamps. After each pass it reviews the returned preview, keeps adjusting (undo is available), then saves when satisfied.

  • Precise pixel placement: draw on a 1..128 pixel-wide and -high canvas with explicit coordinates, rather than asking an image model to imitate pixels.
  • Constrained colors: choose a locked 24-, 144-, or 221-color MARD palette and address colors by code or the palette's Chinese names.
  • Brush sizes: aligned 1x1, 2x2, 4x4 and 8x8 stamps, also used as line/curve/stroke width. An invalid batch is rejected without partially painting it.
  • Immediate previews: creation and drawing return an 8x nearest-neighbor PNG so an image-capable client can display the current canvas.
  • Undo and curves: reverse recent strokes with undo, and draw quadratic / cubic Bezier or smooth multi-point curves with draw_curve.
  • Local export: save PNGs to a configurable directory without overwriting existing work. The model and its API billing remain the client's responsibility.

Use it for small icons, pixel-art illustrations, and experiments with tool-driven AI drawing. It is not a standalone AI model, a photo converter, or a full image editor.

Gallery

Selected existing artwork from this project's output/ directory, copied to docs/images/ for GitHub display. The source canvases below are enlarged 8x in the exported PNGs; these examples do not guarantee identical model output.

Croissant Seaside sunset Temple of Heaven
Pixel-art croissant Pixel-art seaside sunset Pixel-art Temple of Heaven
32x32 canvas 32x32 canvas 64x64 canvas

Install

Download a binary (no Rust required)

Open Releases, expand Assets, and download the archive for your system. Do not choose GitHub's automatically generated Source code archives.

System Archive suffix
Windows x64 x86_64-pc-windows-msvc.zip
Linux x64 (glibc 2.35+, e.g. Ubuntu 22.04+) x86_64-unknown-linux-gnu.tar.gz
macOS Apple Silicon (ARM64) aarch64-apple-darwin.tar.gz
macOS Intel (x64) x86_64-apple-darwin.tar.gz

Extract the archive to a permanent folder. It contains pixeldraw.exe on Windows or pixeldraw on Linux/macOS, plus documentation. No Rust, Cargo, Git or separate model runtime is needed for the server.

Windows PowerShell (example after extraction):

& "C:/Tools/PixelDraw/pixeldraw.exe" --version
& "C:/Tools/PixelDraw/pixeldraw.exe" --help

Linux/macOS (substitute the actual extracted directory):

tar -xzf pixeldraw-v0.2.2-aarch64-apple-darwin.tar.gz
./pixeldraw-v0.2.2-aarch64-apple-darwin/pixeldraw --version

Use the executable's absolute path in your client's MCP configuration:

{
  "mcp": {
    "pixeldraw": {
      "type": "local",
      "command": ["C:/Tools/PixelDraw/pixeldraw.exe", "--output-dir", "C:/Pictures/PixelDraw"],
      "enabled": true
    }
  }
}

On Linux/macOS replace the executable with a path such as /home/you/tools/pixeldraw or /Users/you/tools/pixeldraw, and choose your own output directory. This OpenCode example does not invoke Cargo. Restart or reload the MCP client after configuration. The client starts the server; double-clicking the executable does not open a drawing window.

Each archive has a .sha256 file. Compare it with Get-FileHash <archive> -Algorithm SHA256 in PowerShell, sha256sum -c <archive>.sha256 on Linux, or shasum -a 256 -c <archive>.sha256 on macOS. Keep archive and checksum in the same directory. Checksums verify integrity, not publisher identity. The binaries are not code-signed or notarized; macOS or Windows may show a security warning. Verify the download source before using the OS's per-file approval flow; do not disable system-wide security protections.

Build from source (developers)

Install Rust 1.96.1 or newer using rustup, then:

git clone https://github.com/HHpetra/PixelDraw.git
cd PixelDraw
cargo install --path . --locked
pixeldraw --help

The executable is installed into Cargo's bin directory, which must be on PATH. Prebuilt packages are available starting with v0.1.1. CI checks Windows, Linux and macOS; inspect the Actions results for platform status.

Connect an MCP client

Configure a stdio server with command pixeldraw and arguments ["--output-dir", "/absolute/path/to/art"]. Use an absolute executable path if your desktop client does not inherit Cargo's PATH. On Windows, use a path such as C:/Users/you/Pictures/PixelDraw.

For OpenCode, merge this entry into your configuration:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pixeldraw": {
      "type": "local",
      "command": ["pixeldraw", "--output-dir", "/absolute/path/to/art"],
      "enabled": true
    }
  }
}

Replace the example path with your own. The repository's opencode.json is a development configuration that runs Cargo from the project directory. The wire protocol is covered by an automated smoke test; individual client versions may differ in image display and configuration support.

Draw your first image

Ask your client:

Please use MCP tools to draw a pixel-art seaside sunset. The canvas size should be 32*32.

Use shape tools or precise pixel stamps as needed. After drawing, review the preview and keep adjusting as needed. Minimal tool sequence (arguments shown as JSON):

create_canvas {"width":16,"height":16,"palette":"24"}
draw_circle   {"x":2,"y":2,"diameter":12,"color":"C4","fill":true}
draw_rect     {"x0":2,"y0":2,"x1":13,"y1":13,"color":"A4","fill":false,"brush":2}
save_image    {"filename":"first-icon.png"}

This produces a filled circle and a stroked rectangle in a 128x128 PNG. Tool calls return PNG image content and text; use an MCP client that can display image tool results.

Choosing an export

save_image.output accepts three values; omitting it preserves the existing pixel-only behavior:

output Result with filename: "cat.png"
pixel (default) cat.png: 8x pixel art, with transparent empty cells
pattern cat.png: a labelled bead chart
both cat.png and cat-pattern.png, with both previews returned in that order

Charts place a MARD code in each occupied cell and a light-blue index band with one-based numbers on all four sides. Black counting lines run outward from the center every ten beads, including the outer frame. The header shows size, palette, color count, and bead count, with the Xiaohongshu mark and 豆图工坊 at the right. Square swatches below show the code and count on two lines, such as H2 and (12), without color names. Exported sheets stay within 2048px per side (Xiaohongshu recompresses larger images and bead codes go muddy); codes and index numbers are enlarged, fitted to the cell, and stroke-thickened so they survive that downscale. Rendering uses an embedded font and needs no Python, system fonts, or network. Charts are PNG only, without SVG/PDF, pagination, or physical 1:1 printing. Drawing coordinates remain zero-based.

create_canvas {"width":24,"height":24,"palette":"221","background":"empty"}
draw_pixels   {"pixels":"0 0 H2 1 0 H7 2 0 F5"}
draw_pixels   {"pixels":"2 0 -"}
save_image    {"filename":"cat.png","output":"both"}

The default background: "white" fills the canvas with H2 beads. empty starts without beads. Optional background_color (a MARD code or Chinese name) fills every cell with that bead and remembers it as the current background color; omit it to keep the white or empty default. background: "empty" cannot be combined with background_color. Use - to clear cells, with the same brushes and batch validation as painting. H2 always means a real white bead; empty cells have no code label and are excluded from totals. The example uses two beads. No white region is automatically removed as background.

Both exports use the same snapshot with canonical bead codes and occupancy, never RGB-to-code inference. Overlapping strokes count only the final cells.

Each file is saved atomically. both checks both names before writing, so existing files cause a refusal without writing. The pair is not a transaction: on a late disk error or concurrent collision, the error lists already saved files. Automatically named pairs retry numeric suffixes for collisions. The derived filename must also fit the 200-byte limit; an overlong name fails before writing.

Tools and constraints

Tool Behavior
create_canvas Canvas (background: white default beads or empty). Optional background_color fills every cell with that palette color and stores it as the current background; omitting it preserves the white/empty default. empty cannot be combined with background_color. Width/height 1..128; locks palette 24, 144 or 221 (default). A successful call replaces the current canvas. An unknown color does not.
list_colors Lists the locked palette, or a requested palette before creation. Optional lookup only.
draw_line Line; brush is stroke width 1/2/4/8, coordinates need not align to a grid.
draw_rect Rectangle; fill selects filled vs stroked, stroke uses brush width.
draw_triangle Triangle; fill selects filled vs stroked, stroke uses brush width.
draw_circle Circle anchored at top-left (x, y) with integer diameter ≥ 1 (values above 512 clamp to 512). Occupies diameter × diameter cells; a cell is painted when its center lies inside. Anchor must be on the canvas; right and bottom overflow is clipped. fill selects the disk or its 1-cell outline. Stroke uses brush; fill ignores it.
draw_ellipse Ellipse anchored at top-left (x, y) with integer width and height ≥ 1 (values above 512 clamp to 512). Same center-in-ellipse rule. width == height matches draw_circle of that diameter. Anchor, clipping, fill, and brush match the circle.
draw_diamond Pixel diamond centered on cell (cx, cy), not top-left anchored. rx and ry are diamond half-axes (cells from the center to one side), not the retired ellipse rx/ry. Width and height are 2*rx+1 and 2*ry+1 (always odd). A cell is painted when its center lies inside (abs(di)*ry + abs(dj)*rx ≤ rx*ry, with di = x-cx and dj = y-cy). Values above 255 clamp to 255. The center must be on the canvas; parts past the edge are clipped. fill: false is the 1-cell outline of that fill. Stroke uses brush; fill ignores it. Also a draw_batch op (type: diamond).
draw_curve Curve through [x,y] points: 2=line, 3=quadratic Bezier, 4=cubic Bezier, 5+=Catmull-Rom through every point.
flood_fill Four-connected fill of the seed's current bead code; empty cells are distinct from H2 white beads. Use - to clear a region back to empty.
fill_background Overwrites every cell with one palette color (MARD code or Chinese name), including empty cells and existing artwork, and sets the remembered background color to that color. Invalid colors leave the canvas and its background color unchanged. One undo step when any cell changes or the remembered color differs; no step when both already match. Undo restores the previous background color. Also a draw_batch op.
move_region Moves an inclusive rectangle (reversed corners are normalized). Address with relative dx/dy or absolute destination top-left tx/ty, exactly one pair. Empty cells move with the block. The source is filled with the current background bead, or left empty when the background is empty. The remembered background color is unchanged. A source endpoint or destination rectangle outside the canvas rejects the call. No undo step when the move would not change any cell. Also a draw_batch op.
copy_region Same parameters as move_region. The source stays, and empty cells overwrite the destination.
draw_batch Ordered atomic batch; any failure rejects the whole batch; one final preview and one undo step. Ops include fill_background, move_region, copy_region, and motif.
draw_pixels Whitespace-separated x y color triples; - clears a cell.
draw_motif Places one embedded motif by Chinese name at the top-left (x, y) of its bounding box (the scaled box when scale is set). One canonical color per call; - clears cells to empty, which is distinct from an H2 white bead. scale is an integer 1–8; omitting it means 1, and JSON null is rejected. Each occupied cell becomes a solid scale×scale block. Gaps in the bitmap are not painted. The anchor must be on the canvas; overflow is clipped. Existing cells are overwritten. The remembered background color is unchanged. One undo step per call, or none when every occupied cell is clipped away. Unknown names, a missing or out-of-range dice face, a face on any other name, a scale outside 1–8, an unknown color, or an anchor outside the canvas reject the call with the canvas unchanged. Also a draw_batch op (type: motif).
undo Reverses recent drawing steps (steps optional, default 1). Successful draws are one step each; draw_batch is one step; create_canvas clears history.
save_image Exports pixel (default), pattern, or both as PNG without overwriting existing files.
  • Prefer draw_batch for multi-stroke work; do not call drawing tools in parallel. Review the preview and keep adjusting.
  • Stroke/line brush sizes are 1, 2, 4 or 8, expanded as an N×N square toward the bottom-right from each raster point (same footprint as draw_pixels). Fills and flood fill ignore brush size.
  • For draw_pixels, brush positions must be multiples of the brush size, and the entire square must fit inside the canvas.
  • Invalid drawing batches leave the canvas unchanged. Repeated positions are applied in order. Colors use MARD codes or the active palette's Chinese names.
  • fill_background replaces every cell and updates the remembered background color. It does not stop at a connected region the way flood_fill does, and it does not accept -. Undo restores the previous background color with the cells.
  • Circle and ellipse anchors (x, y) must stay inside the canvas. diameter, width, and height are integers ≥ 1; values above 512 are treated as 512. Cells past the right or bottom edge are clipped. A cell is included when its center lies inside the ellipse. fill: false paints the 1-cell outline of that fill. On circle and ellipse, the old names cx, cy, radius, rx, and ry are rejected. draw_diamond is centered on cell (cx, cy), which must be on the canvas; it is not top-left anchored. rx and ry are diamond half-axes (not the retired ellipse axes): width and height are 2*rx+1 and 2*ry+1 (always odd). Values above 255 are treated as 255. Parts past the edge are clipped. fill: false is the 1-cell outline of that fill. Line ends, curve points, and flood-fill seeds must stay inside the canvas. A region move or copy is rejected entirely when a source endpoint or the destination rectangle falls outside the canvas; the canvas and undo history stay unchanged. A motif anchor (x, y) must stay inside the canvas. scale is an integer from 1 to 8; omitting it means 1, and JSON null is rejected. face belongs only to 骰子面 and is an integer from 1 to 6. Omitting face means it was not supplied; JSON null still counts as supplied and is rejected. 箭头-左 is locked at 4×3 as .#../####/..#.: the spec row . . # . . has one extra empty cell past the declared width. That cell is dropped, the six occupied coordinates stay, and the bitmap is not replaced by the left-right mirror of 箭头-右. The 32 names (骰子面 expands to six bitmaps): 十字 (3×3, 5), 叉 (3×3, 5), 品字-缺左上 (2×2, 3), 品字-缺右上 (2×2, 3), 斜线-短 (2×2, 2), 斜线-长 (3×3, 3), 四点 (3×3, 4), T字-下 (3×3, 5), T字-上 (3×3, 5), T字-右 (3×3, 5), T字-左 (3×3, 5), 拐角-左上 (2×2, 3), 拐角-右上 (2×2, 3), 拐角-左下 (2×2, 3), 拐角-右下 (2×2, 3), 箭头-上 (3×4, 6), 箭头-下 (3×4, 6), 箭头-左 (4×3, 6), 箭头-右 (4×3, 6), 对勾 (3×3, 4), 感叹号 (1×5, 4), 四芒闪光 (3×3, 4), 五角星 (5×5, 13), 闪电 (3×5, 7), 小爱心 (5×4, 11), 水滴 (3×4, 7), 小花 (5×5, 13), 骰子面 (3×3; face=1 is 1 cell, face=2 is 2, face=3 is 3, face=4 is 4, face=5 is 5, face=6 is 6), 扑克-红心 (5×4, 11, same bitmap as 小爱心), 扑克-方块 (5×5, 13), 扑克-梅花 (5×5, 12), 扑克-黑桃 (5×5, 13).
  • Only one canvas is held in memory per server instance. Restarting loses unsaved work. Undo is in-memory only (up to 64 steps) and is cleared by create_canvas. There is no import, session persistence, or native-size export.
  • Pixel previews are enlarged 8x with nearest-neighbor sampling; bead charts have a separate grid layout. A MARD code has the same Chinese name and RGB in the 24-, 144-, and 221-color palettes.

Output and troubleshooting

--output-dir PATH selects the destination. The default is ./output relative to the server's working directory, not the source or executable directory. Use a directory you control; this local tool is not a filesystem sandbox.

Filenames accept ASCII letters, digits, dots, underscores and hyphens, with a maximum of 200 bytes including the appended .png extension. Paths, trailing dots and Windows device names are rejected. Omit filename for an automatic name with collision retries; explicit existing names return an error.

If the server appears idle in a terminal, that is expected: it waits for MCP messages on stdin. Logs go to stderr. For permission failures, select a writable output directory. If colors are rejected, query list_colors rather than assuming names transfer between palettes. Use RUST_LOG=debug for diagnostics.

Development and licensing

See CONTRIBUTING.md for checks and AGENTS.md for detailed drawing guidance and color tables. Code is licensed under MIT; see THIRD_PARTY.md for palette provenance and the scope of third-party rights. Only the selected gallery images are included; local reference images, screenshots and the rest of output/ remain excluded.

About

让 AI 通过 MCP 精确绘制像素画的本地工具。 A local tool that allows AI to precisely draw pixel art via MCP

Resources

Contributing

Stars

14 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages