Skip to main content
Glama
Sign In
Pixelorama MCP Bridge

Pixelorama MCP Bridge

by ramonsamagaio
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

šŸ–Œļø Pixelorama MCP Bridge

Local MCP server for deterministic Pixelorama control from any MCP-compatible AI agent. Create, edit, import/export spritesheets, and save .pxo projects programmatically via Godot extension + file-queue transport.

What is it

An MCP (Model Context Protocol) server that connects any compatible AI agent to Pixelorama via a Godot extension + file-queue transport. It allows creating projects, editing individual pixels, importing/exporting spritesheets, and saving .pxo projects programmatically.

Related MCP server: pixelorama-game-asset-mcp

Compatible Agents

Works with any MCP-compatible agent:

  • Hermes Agent ā€” mcp_servers in config.yaml

  • Claude Code / Claude Desktop ā€” mcpServers in claude_desktop_config.json or .mcp.json

  • ChatGPT / Codex ā€” MCP connector settings

  • Cursor, Windsurf, Cline, Continue, Aider, etc. ā€” any MCP-compatible client

  • Custom agents ā€” any tool that speaks MCP over stdio

Requirements

  • Python 3.11+ (tested on 3.11.15)

  • Pixelorama (Windows/Linux/macOS) ā€” download

  • Any MCP-compatible AI agent (Hermes, Claude, GPT, Cursor, etc.)

Installation

1. Clone the repository

git clone https://github.com/ramonsamagaio/Hermes-Pixelorama-MCP.git
cd Hermes-Pixelorama-MCP

2. Install dependencies

pip install mcp>=1.12,<2 pillow>=11,<13
# or via uv:
uv pip install -e .

3. Install the extension into Pixelorama

python -m pixelorama_bridge.installer \
  --project-root . \
  --pixelorama-user-dir "$APPDATA/pixelorama"

This will:

  • Copy extension/src/Extensions/HermesBridge.zip to Pixelorama's extensions folder

  • Generate an auth token at pixelorama_user_dir/hermes_bridge/token

  • Enable the extension in Pixelorama's config.ini

4. Configure your agent

Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  pixelorama:
    command: python
    args:
      - -m
      - pixelorama_bridge.mcp_server
    env:
      PIXELORAMA_BRIDGE_ROOT: /c/Users/ramon/AppData/Roaming/pixelorama/hermes_bridge
      PIXELORAMA_EXE: /c/Users/ramon/Downloads/pixelorama.exe

Claude Code / Claude Desktop

Add to ~/.claude.json (global) or .mcp.json (project-level):

{
  "mcpServers": {
    "pixelorama": {
      "command": "python",
      "args": ["-m", "pixelorama_bridge.mcp_server"],
      "env": {
        "PIXELORAMA_BRIDGE_ROOT": "/home/user/.local/share/pixelorama/hermes_bridge",
        "PIXELORAMA_EXE": "/home/user/Downloads/pixelorama.AppImage"
      }
    }
  }
}

Then restart Claude:

claude mcp list          # verify it appears
claude                   # tools are now available

ChatGPT / Codex (OpenAI)

Use an MCP connector or configure via your agent's settings. Example for a custom script:

python -m pixelorama_bridge.mcp_server

Cursor / Windsurf / Cline / Continue

Add to your MCP settings (usually in .cursorrules, .windsurf/mcp.json, .cline/mcp.json, or .continue/config.json):

{
  "mcpServers": {
    "pixelorama": {
      "command": "python",
      "args": ["-m", "pixelorama_bridge.mcp_server"],
      "env": {
        "PIXELORAMA_BRIDGE_ROOT": "/home/user/.local/share/pixelorama/hermes_bridge",
        "PIXELORAMA_EXE": "/path/to/pixelorama"
      }
    }
  }
}

Aider

aider --mcp-server "python:-m:pixelorama_bridge.mcp_server"

Adjust paths according to your system.

5. Restart your agent

After configuring, restart your agent. The tools will be available once Pixelorama is running with the HermesBridge extension loaded.

Available Tools

Once connected, the agent has access to:

Tool

Description

pixelorama_status

Check if Pixelorama and HermesBridge extension are active

pixelorama_launch

Launch Pixelorama (optionally with project)

pixelorama_create_project

Create transparent RGBA project with dimensions and frames

pixelorama_open_project

Open existing .pxo project

pixelorama_project_info

Return dimensions, frame/layer counts

pixelorama_set_frame_png

Replace cel with PNG (same size)

pixelorama_get_frame_png

Export cel to PNG

pixelorama_set_pixels

Apply exact [x,y,r,g,b,a] edits

pixelorama_set_frame_duration

Set frame duration multiplier

pixelorama_save_project

Save as .pxo

pixelorama_export_spritesheet

Export frames to transparent PNG spritesheet

pixelorama_import_spritesheet

Split spritesheet and import as real animation frames

Example Usage

Create a 32x32 project with 6 frames, import the spritesheet:
path=spritesheet.png, frame_width=32, frame_height=32, frame_count=6, columns=6

Now edit frame 2:
set frame=2, path=edited_frame.png

Save the project:
save_project path=animation.pxo

Export the final spritesheet:
export_spritesheet path=output.png, frame_count=6, columns=6

Architecture

Hermes-Pixelorama-MCP/
ā”œā”€ā”€ pyproject.toml                    # Dependencies (mcp, pillow)
ā”œā”€ā”€ extension/
ā”‚   ā””ā”€ā”€ src/Extensions/HermesBridge/
ā”‚       ā”œā”€ā”€ Main.gd                   # Godot extension (file-queue listener)
ā”‚       ā”œā”€ā”€ Main.tscn                 # Godot scene
ā”‚       ā””ā”€ā”€ extension.json            # Metadata
ā”œā”€ā”€ src/pixelorama_bridge/
ā”‚   ā”œā”€ā”€ __init__.py
ā”‚   ā”œā”€ā”€ mcp_server.py                 # FastMCP server (tools)
ā”‚   ā”œā”€ā”€ transport.py                  # FileQueueTransport (request/response)
ā”‚   ā”œā”€ā”€ image_ops.py                  # split/build spritesheet, apply pixels
ā”‚   ā”œā”€ā”€ installer.py                  # Install extension + generate token
ā”‚   ā””ā”€ā”€ packaging.py                  # Build .zip of extension
ā””ā”€ā”€ tests/                            # pytest suite

License

MIT

Tool Schema Changelog

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

Loading tool schema changelogā€¦

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • pixelorama-game-asset-mcp

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

    • godot-omni

      bebabinlarsson-blip
      A
      license
      B
      quality
      B
      maintenance
      Enables AI assistants to automate the Godot Engine editor, including scene authoring, node transforms, tilemap editing, animation, shaders, and live GDScript execution via MCP.
      100
      30
      MIT

    • atelier

      marmikshah
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to create layered pixel-art sprites and animations, inspect pixels, and export images, spritesheets, GIFs, APNGs, and TrueType pixel fonts. Documents and edits stay local, accessible over stdio MCP or callable directly from a shell.
      40
      MIT