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.
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 withdraw_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.
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 |
|---|---|---|
| 32x32 canvas | 32x32 canvas | 64x64 canvas |
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" --helpLinux/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 --versionUse 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.
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 --helpThe 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.
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.
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.
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.
| 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_batchfor multi-stroke work; do not call drawing tools in parallel. Review the preview and keep adjusting. - Stroke/line
brushsizes are 1, 2, 4 or 8, expanded as anN×Nsquare toward the bottom-right from each raster point (same footprint asdraw_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_backgroundreplaces every cell and updates the remembered background color. It does not stop at a connected region the wayflood_filldoes, 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, andheightare 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: falsepaints the 1-cell outline of that fill. On circle and ellipse, the old namescx,cy,radius,rx, andryare rejected.draw_diamondis centered on cell(cx, cy), which must be on the canvas; it is not top-left anchored.rxandryare diamond half-axes (not the retired ellipse axes): width and height are2*rx+1and2*ry+1(always odd). Values above 255 are treated as 255. Parts past the edge are clipped.fill: falseis 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.scaleis an integer from 1 to 8; omitting it means 1, and JSONnullis rejected.facebelongs only to 骰子面 and is an integer from 1 to 6. Omittingfacemeans it was not supplied; JSONnullstill 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-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.
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.