Skip to main content
Glama
pixelorama-mcp
by Aeroscoop

pixelorama-mcp (versie Aeroscoop)

Aangepaste versie van CyberIce2077/pixelorama-mcp (MIT, zie LICENSE). Gemaakt voor Nestar, maar werkt met elk project in Pixelorama. Agents: lees eerst AGENTS.md.

Wat er anders is dan het origineel

  • Werkt met Pixelorama 1.2 (uitbreidings-API 10). Sinds 1.2 groeit een laag mee met de inhoud (een nieuwe laag is 1 × 1 pixel, met een verschuiving). Het origineel schreef daarbuiten en tekende niets. Nu werkt elke opdracht op een kopie ter grootte van het werkvlak en laat de laag groeien en krimpen zoals Pixelorama zelf.

  • Nieuwe tools: rename_layer, get_palette, select_palette, create_palette, set_color_mode, resize_canvas, undo, redo.

  • Kleuren als paletvakje: @n = vakje n (vanaf 0) van het gekozen palet; read_pixels meldt palette_slots; get_project meldt kleurmodus en palet.

  • Getest met Pixelorama v1.2.4 op Windows (aeropc), 15-11-2026.

Related MCP server: pixel-mcp

Installeren

Zoals hieronder bij Setup, met deze repo in plaats van het origineel. Daarna in de Claude-app (instellingenbestand, mcpServers), Claude Code (claude mcp add pixelorama -- node <pad>/dist/index.js) of Codex (codex mcp add) als lokale stdio-server. Nooit openzetten naar internet.

Installeren op Linux

Getest op Windows; deze stappen volgen het installatiescript (scripts/install-extension.mjs), dat op Linux ~/.local/share/pixelorama gebruikt.

  1. Pixelorama 1.2 of nieuwer. Neem de losse Linux-versie van GitHub-releases (zip of tar.gz, geen installatie nodig). Uitpakken en Pixelorama.x86_64 starten. Gebruikt die de map ~/.local/share/pixelorama; dan werkt stap 3 vanzelf.

    • Flatpak (com.orama_interactive.Pixelorama) kan ook, maar die gebruikt ~/.var/app/com.orama_interactive.Pixelorama/data/pixelorama. Kopieer bij stap 3 de zip dan zelf naar de map extensions daarin.

    • Snap liever niet: die zit afgeschermd en het is niet getest.

  2. Node.js 22 of nieuwer (node -v). Te oud of niet aanwezig: installeer via nvm (nvm install 22) of het pakket van NodeSource.

  3. Koppeling bouwen en de uitbreiding plaatsen:

    git clone https://github.com/Aeroscoop/pixelorama-mcp.git ~/projects/pixelorama-mcp
    cd ~/projects/pixelorama-mcp
    npm install
    npm run install-extension
  4. Aanzetten: Pixelorama opnieuw starten, dan Preferences > Extensions > Pixelorama MCP aanvinken.

  5. Aan de agent koppelen (lokale stdio-server, nooit naar internet):

    • Claude Code: claude mcp add pixelorama -- node ~/projects/pixelorama-mcp/dist/index.js

    • Codex: codex mcp add pixelorama -- node ~/projects/pixelorama-mcp/dist/index.js

    • Claude-app: in ~/.config/Claude/claude_desktop_config.json onder mcpServers een blok "pixelorama": {"command": "node", "args": ["/home/<naam>/projects/pixelorama-mcp/dist/index.js"]}. Gebruik het volledige pad, geen ~. Daarna de Claude-app opnieuw starten.

  6. Controleren: Pixelorama open met een project, dan de agent get_project laten doen. Antwoordt die met maat en lagen, dan werkt het. Geen verbinding: kijk of de uitbreiding aanstaat en of poort 7651 vrij is (ss -ltn | grep 7651).

Paletten meenemen. Projectpaletten zitten in het .pxo-bestand en gaan vanzelf mee. Algemene paletten (zoals Winter 25, Winterhol dag, Winterhol nacht) zijn losse .json-bestanden: kopieer ze van %APPDATA%\Pixelorama\Palettes (Windows) naar ~/.local/share/pixelorama/Palettes (Linux) en start Pixelorama opnieuw.

Bijwerken na nieuwe wijzigingen in deze repo: git pull && npm install && npm run install-extension, daarna Pixelorama opnieuw starten.

Nog te doen

  • Betere namen voor stappen in de geschiedenis (#1).

  • Openen, bewaren en exporteren beperken tot één map (#2).


Originele README

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.

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

21 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.

create_paletteB

Create a project palette from a list of colors (slot 0 first) and select it. Use the same slot order for a day and a night palette.

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

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_rectB

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_paletteA

Show the palette selected in Pixelorama (slot number and color of every swatch, slot 0 first), the names of all palettes, and the color mode. In draw_pixels and fill_rect a color '@n' means slot n of this palette.

Inputs: no named parameters.

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.

redoA

Redo the last n undone steps in the active project, like Ctrl+Y. Returns the names of the steps redone.

Inputs: steps.

rename_layerC

Rename a layer. Layer 0 is the bottom layer.

Inputs: name (required), layer (required).

resize_canvasA

Change the canvas size without scaling. anchor is where the old image stays: bottom (default, centered horizontally), top, center, left, right, or combinations like bottom-left.

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

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.

select_paletteA

Select a palette by name (global or project palette). In indexed mode the whole image recolors to it, slot by slot.

Inputs: name (required).

set_color_modeA

Switch the project between 'indexed' (every pixel is a palette slot) and 'rgba'. One undo step.

Inputs: mode (required).

undoA

Undo the last n steps in the active project, like Ctrl+Z. Returns the names of the steps undone.

Inputs: steps.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 21 tools

    Disambiguation4/5

    Most tools target clearly distinct operations: draw_pixels vs fill_rect vs clear_cel, and add_layer vs add_frame vs select_cel are easy to separate. The closest pair is get_image (blended visual preview) vs read_pixels (raw grid data) and get_project (metadata), but the descriptions make the distinction clear enough.

    Naming Consistency4/5

    Nearly all names follow a snake_case verb_noun or verb_target pattern (get_project, draw_pixels, rename_layer, resize_canvas, export_png), with only bare verbs undo/redo as a natural exception. Minor deviation: the create verb is inconsistent ('new_project' vs 'create_palette', 'add_layer', 'add_frame').

    Tool Count4/5

    21 tools is on the heavy side but each maps to a real pixel-art workflow: project lifecycle, drawing, layers, frames, palettes, and export. Nothing looks redundant, though a few could be consolidated (e.g. layer/frame manipulation helpers).

    Completeness3/5

    Core creation flows are covered (new/open project, draw, fill, layers, frames, palettes, save/export, undo/redo), but the lifecycle is asymmetric: you can add layers and frames yet there is no delete_layer, delete_frame, duplicate_frame, or layer reordering/visibility toggle. These are common operations that will force agents into workarounds.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables LLMs to create and edit pixel art reliably with support for layers, frames, symmetry, and various drawing tools.
      70
      MIT No Attribution
    • 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