AI agents · MCP

Give your AI agent a pixel art editor

QxSprite's built-in Model Context Protocol server lets agents create sprites, draw, animate, look at their work and export game-ready assets — while you watch and collaborate.

Agent editing live — QxSprite
AI agent editing a sprite live in QxSprite

How it works

  • Editor open → live mode. The MCP server finds the running QxSprite window through a local, token-protected bridge on 127.0.0.1. Agent edits appear instantly, a toast shows what the agent is doing, and every change is undoable with ⌘Z / Ctrl+Z.
  • Editor closed → headless mode. The same tools run in the MCP process directly on files. Use save_sprite to persist work. Great for CI and background agents.
  • Want to watch? An agent can call launch_editor to open the GUI and switch to live mode.

Set up in one minute

Install QxSprite, then open Help ▸ AI Agents (MCP) Setup… in the app — it shows these snippets with the exact paths for your machine. On macOS with the app in /Applications:

Claude Code

Terminal
claude mcp add qxsprite -e ELECTRON_RUN_AS_NODE=1 -- "/Applications/QxSprite.app/Contents/MacOS/QxSprite" "/Applications/QxSprite.app/Contents/Resources/cli/qxsprite.cjs" mcp

Claude Desktop, Cursor, VS Code, Windsurf, Codex and other MCP clients

MCP config (JSON)
{
  "mcpServers": {
    "qxsprite": {
      "command": "/Applications/QxSprite.app/Contents/MacOS/QxSprite",
      "args": [
        "/Applications/QxSprite.app/Contents/Resources/cli/qxsprite.cjs",
        "mcp"
      ],
      "env": {
        "ELECTRON_RUN_AS_NODE": "1"
      }
    }
  }
}

Paths on Windows and Linux

Windows (portable zip): use the folder you extracted, e.g. C:\Tools\QxSprite\QxSprite.exe with C:\Tools\QxSprite\resources\cli\qxsprite.cjs. Linux: ./qxsprite with ./resources/cli/qxsprite.cjs inside the extracted folder. If Node.js 20+ is installed you can use "command": "node" with just the .cjs path, or launch the app binary with --mcp.

Try these prompts

  • “Use QxSprite to draw a 32×32 knight in the PICO-8 palette. Check it with render_preview and fix anything that looks off.”
  • “Add a 6-frame walk cycle to the knight, tag it ‘walk’, and export a sprite sheet with JSON to assets/knight.png.”
  • “Open enemies.aseprite, recolor the slime from green to purple across all frames, and save it.”
  • “Make a 16×16 tileset of grass, dirt and stone tiles and export each tile as its own PNG.”

Tips for agents

  • paint_grid is the fastest way to draw detail: each string is a row, each character a pixel, mapped through a legend.
  • read_pixels with format: "grid" returns rows + legend in the same shape — read, modify, paint back.
  • Always verify with render_preview (add grid: true to count coordinates).
  • Coordinates start at (0,0) top-left. Frame and layer indices are 0-based; layer 0 is the bottom.

Command line

Shell
qxsprite export hero.qxs --sheet build/hero.png --json hash --scale 2
qxsprite export hero.qxs --gif hero.gif --tag walk --scale 4
qxsprite convert hero.aseprite hero.qxs
qxsprite run steps.json      # a list of tool calls: [{"tool": "...", "args": {...}}]
qxsprite tools --json        # every tool with its JSON schema

All 37 tools

ToolWhat it does
list_spritesList open sprites and which one is active. Also reports whether you are connected to the live GUI editor or running headless.
new_spriteCreate a new sprite and make it active. Typical sizes: 16x16, 32x32, 64x64. The palette is a set of swatches you can reference by index in any color argument.
open_spriteOpen a .qxs (native), .aseprite/.ase, or .png file and make it active. Relative paths resolve against your working directory.
save_spriteSave a sprite. Use .qxs (native, lossless) or .aseprite (lossless, Aseprite-compatible). Saving to .png writes frame 0 flattened; .gif writes the animation. Without path, saves to the current file.
close_spriteClose an open sprite. Fails if it has unsaved changes unless discard_changes is true.
get_sprite_infoDimensions, layers (top to bottom), frames with durations, tags, palette (index:hex), active layer/frame, and save state.
set_activeChange the active sprite, layer, and/or frame. Tools default to the active layer and frame. In the GUI this also moves the user's view.
draw_pixelsSet individual pixels. Each entry is {x, y, color?}; entries without color use the top-level color. Out-of-bounds pixels are ignored. Use color "transparent" to erase.
paint_gridPaint a block of pixels from text rows — the easiest way to draw pixel art. Each string in `rows` is one row; each character is one pixel. '.' and ' ' leave the pixel unchanged (unless erase_dots is true). Map other characters to colors with `legend`, e.g. {"k":"#000000","s":"#f2c79a","x":"transparent"}. Without a legend, 0-9, a-z, A-Z mean palette indices 0-61 (a=10, z=35, A=36). Tip: read_pixels with format "grid" returns rows + legend in this exact format, so you can read, edit and paint back.
read_pixelsRead pixels from a region. format "grid" (default) returns text rows plus a legend (char -> hex), using palette-index characters where colors match the palette and "." for transparent — feed it straight back into paint_grid. format "list" returns only non-transparent pixels as [x, y, hex]. Omit layer (or pass composite:true) to read what is visible (all visible layers merged).
draw_lineDraw a pixel-perfect line between two points (inclusive). Optional brush size.
draw_rectDraw a rectangle outline or filled rectangle.
draw_ellipseDraw an ellipse/circle inscribed in the given bounding box (outline or filled). For a circle of diameter d at (x,y) top-left, use width=height=d.
fillPaint-bucket fill starting at (x,y). contiguous=false replaces every matching pixel on the layer. sample_merged uses the visible image to decide the fill area (still paints on the target layer).
clearErase pixels (make transparent) in a region of a cel, or the whole cel when no region is given.
replace_colorReplace every pixel of one color with another. scope: "cel" (one layer+frame), "layer" (all frames of a layer), "frame" (all layers of a frame), or "sprite" (everything).
transformFlip, rotate, shift (scroll) or outline pixels. scope "cel" = active/given layer+frame; "layer" = that layer in all frames; "frame" = all layers of that frame; "sprite" = everything (rotate_90/270 on "sprite" swaps width/height). Rotating 90/270 at smaller scopes requires a square canvas. "outline" adds a 1px outline of `color` around opaque pixels.
copy_pixelsCopy a rectangular region from one layer/frame to a position on another (or the same) layer/frame. Great for reusing parts between animation frames. mode "over" skips transparent source pixels; "replace" copies them too.
import_imagePaste a PNG file onto a layer/frame at (x, y). Set new_layer to create a layer for it.
color_statsCount the colors used in a frame (composite) or across the whole sprite, and flag colors that are not in the palette. Useful for checking palette discipline.
layerLayer operations. action: "add" (name?, index? — default on top of the active layer; becomes active), "delete", "update" (name/visible/locked/opacity 0-255), "move" (index: new 0-based position, 0 = bottom), "duplicate", "merge_down" (into the layer below), "flatten" (merge all visible layers into one). Target layer via `layer` (default: active layer).
frameAnimation frame operations (0-based indices). action: "add" (insert `count` empty frames after `frame`, default after the active frame), "duplicate" (copy `frame` and insert the copy right after it; repeat with count), "delete", "move" (frame -> index), "set_duration" (duration ms; applies to `frame`, or to all frames when all=true). Tags are adjusted automatically.
tagAnimation tags name a range of frames (e.g. "idle" 0-3, "walk" 4-9) and are exported in sprite-sheet JSON for game engines. action "add" | "update" | "delete". direction: forward, reverse, pingpong, pingpong_reverse.
palettePalette operations. action: "get"; "list_presets"; "load_preset" (preset); "set" (colors: replaces palette); "add" (colors appended); "remove" (index); "edit" (index + color: changes swatch only); "replace" (index + color: also recolors every pixel using the old color); "from_sprite" (palette = colors used in the sprite); "load_file"/"save_file" (path: .gpl, .hex, .pal, .txt).
resize_canvasChange the canvas size without scaling pixels. anchor decides where existing art sits (default "center"). Pixels outside the new canvas are cropped.
cropCrop the whole sprite (all layers/frames) to a rectangle, or to the bounding box of all visible content when to_content is true.
scale_spriteScale the whole sprite with nearest-neighbor (keeps pixels crisp). Provide factor (e.g. 2 or 0.5) or explicit width/height.
render_previewRender the sprite to an image so you can SEE your work. Returns a PNG. Choose a single frame (frame), a list (frames), or a tag; multiple frames are laid out left-to-right in order. Transparent areas show as a dark checkerboard. scale defaults to fit ~512px. grid:true draws pixel grid lines (helps you count coordinates); gridlines every 8 px are brighter.
export_pngExport one frame (all visible layers merged) as a PNG, optionally scaled up.
export_framesExport each frame as its own PNG. path must contain "{frame}" (replaced with the 0-based index, zero-padded) e.g. "out/walk_{frame}.png". Optional "{tag}" placeholder.
export_spritesheetExport frames into one sprite-sheet PNG plus Aseprite-compatible JSON (frames rects, durations, tags) that game engines and importers understand. The JSON goes next to the PNG with .json extension unless json is "none".
export_gifExport the animation (or one tag, honoring its direction) as an animated GIF, scaled up for sharing.
import_sprite_sheetOpen a sprite-sheet PNG as a new animated sprite by slicing it into frames of frame_width x frame_height (left-to-right, top-to-bottom). Empty cells are skipped.
undoUndo the last change(s) on a sprite (agent and human edits share one history).
redoRedo previously undone change(s).
editor_statusShow whether tools run in the live editor or headless, and switch between them.
launch_editorStart the QxSprite GUI (if installed) and connect to it so the user can watch.
QxSprite icon

Ready to pair with your agent?