Skip to main content
Glama

pixelorama-mcp

Lets AI agents like Claude Code draw pixel art in Pixelorama through MCP.

It has two parts: a Pixelorama extension that runs inside the editor, and an MCP server that the agent talks to. The agent works on whatever is open in Pixelorama, you watch it happen on the canvas, and every change can be undone with Ctrl+Z like any other edit.

Drawing format

Agents draw with a character grid and a palette, which is far easier for a language model than coordinates:

{
  "palette": { "o": "#7a4a12", "y": "#f2c230", "h": "#fff2a8" },
  "rows": [
    "..oooo..",
    ".ohyyyo.",
    "oyyyyyyo",
    ".oyyyyo.",
    "..oooo.."
  ],
  "x": 4,
  "y": 4
}

Characters missing from the palette (like .) leave pixels alone. read_pixels returns existing art in the same format, so an agent can read a sprite, change it and write it back.

Related MCP server: Aseprite MCP

Tools

Tool

What it does

get_project

Size, frames, layers and the current cel

new_project

New canvas in a new tab

open_file

Open a .pxo or an image

draw_pixels

Draw a character grid

fill_rect

Fill a rectangle, or the whole cel

clear_cel

Erase a cel

read_pixels

Read pixels back as a character grid

get_image

Image of a frame, scaled up so the agent can see it

add_layer, add_frame

Add a layer or frame and select it

select_cel

Change the current frame/layer

save_project

Save as .pxo

export_png

Export a frame, or all frames as a sprite sheet

Frames are counted from 0, left to right. Layers are counted from 0 at the bottom.

Setup

Requires Pixelorama 1.2 (extension API 9) and Node.js 22 or newer.

git clone https://github.com/CyberIce2077/pixelorama-mcp.git ~/projects/pixelorama-mcp
cd ~/projects/pixelorama-mcp
npm install
npm run install-extension

npm install builds the server and packs the extension into dist/PixeloramaMCP.zip. install-extension copies it into Pixelorama's extensions folder. You can also install the zip from Pixelorama's Preferences > Extensions.

Restart Pixelorama, enable Pixelorama MCP in Preferences > Extensions, then add the server to Claude Code:

claude mcp add pixelorama -- node ~/projects/pixelorama-mcp/dist/index.js

How it works

agent  <--stdio-->  pixelorama-mcp server  <--TCP 127.0.0.1:7651-->  Pixelorama extension

The extension listens on localhost only and speaks one JSON object per line. Any connection that sends something else, such as a web page trying to reach the port over HTTP, is dropped before a command runs.

The port is 7651. To change it, set PIXELORAMA_MCP_PORT for the server and PORT in extension/src/Extensions/PixeloramaMCP/Main.gd.

Limitations

  • Only pixel layers can be drawn on. Group, tilemap, 3D and audio layers are reported but not editable.

  • Commands act on the project in the active tab.

  • No brushes, selections or tools yet; drawing is pixels and rectangles.

License

MIT

Available Tools

13 tools
add_frameA

Add an empty frame. By default it goes after the last frame.

Inputs: after.

add_layerB

Add a pixel layer. By default it goes on top of all layers.

Inputs: name, above.

clear_celB

Erase every pixel of one cel (a layer in a frame).

Inputs: frame, layer.

draw_pixelsA

Draw pixels from a character grid. Each string in rows is one row of pixels; each character is looked up in palette. Characters that are not in the palette (such as '.') leave the pixel unchanged, so map a character to "transparent" to erase. Example: palette {"o": "#e8a33d", "d": "#7a4a12"}, rows [".oo.", "oddo", ".oo."]. The whole call is one undo step in Pixelorama.

Inputs: rows (required), palette (required), x, y, +2 more.

export_pngA

Export the current frame, or all frames as a horizontal sprite sheet, to a PNG file. Layers are blended the same way Pixelorama shows them.

Inputs: path (required), frame, scale, all_frames.

fill_rectA

Fill a rectangle with one color. Leave out the position and size to fill the whole canvas.

Inputs: color (required), x, y, frame, +3 more.

get_imageA

Show a frame with all visible layers blended, scaled up with nearest-neighbour so pixels stay sharp.

Inputs: frame, scale.

get_projectA

Describe the project open in Pixelorama: size, frames, layers and the current cel.

Inputs: no named parameters.

new_projectB

Create a new, empty project in a new tab and switch to it.

Inputs: width (required), height (required), name.

open_fileA

Open a .pxo project or an image (png, jpg, webp, bmp, tga) in a new tab.

Inputs: path (required).

read_pixelsB

Read pixels of one cel as a character grid with a palette, in the same format draw_pixels takes. '.' is transparent. At most 16384 pixels per call.

Inputs: x, y, frame, layer, +2 more.

save_projectA

Save the current project as a .pxo file. Without a path it saves to where it was last saved.

Inputs: path.

select_celC

Make a frame/layer the current one in Pixelorama.

Inputs: frame, layer.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 13 tools

    Disambiguation4/5

    Each tool maps to a distinct action (draw, read, fill, clear, export, select), and descriptions clarify boundaries well. The only mild overlap is get_project (metadata description) versus get_image (rendered preview), but their descriptions make the distinction clear.

    Naming Consistency5/5

    All 13 tools use a consistent snake_case verb_noun pattern (get_project, add_layer, draw_pixels, export_png, save_project). No mixing of conventions or vague single-word names.

    Tool Count5/5

    13 tools sits squarely in the ideal 3-15 range and each one covers a distinct editing or project operation. Nothing feels padded or missing from a count perspective.

    Completeness3/5

    Project lifecycle (new/open/save/export) and drawing/reading are well covered, but the surface is create-only for structure: add_layer and add_frame exist with no delete_layer or remove_frame, and there is no layer/frame reordering, visibility, or undo control. Agents will hit dead ends when they need to remove or reorder content.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables AI to directly control Pixelorama for real-time 2D game asset creation, including layer-based pixel drawing, animation frames, automatic quality checks, and export of spritesheets, .pxo files, and Godot resources.
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables an AI agent to create and edit pixel art directly in Aseprite — building sprites, layers, frames, animation tags and palettes, painting pixels and primitives, inspecting the rendered result, and exporting GIFs or sprite sheets. All work lands on real .aseprite files that can be opened and edited by hand.
      43
      1
      MIT