Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Pixelorama MCP Bridge Create a 32x32 project with 6 frames, import spritesheet.png as the frames, then export the final spritesheet."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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: aseprite-mcp
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
Python 3.11+ (tested on 3.11.15)
Pixelorama (Windows/Linux/macOS) ā download
Any MCP-compatible AI agent (Hermes, Claude, GPT, Cursor, etc.)
git clone https://github.com/ramonsamagaio/Hermes-Pixelorama-MCP.git
cd Hermes-Pixelorama-MCPpip install mcp>=1.12,<2 pillow>=11,<13
# or via uv:
uv pip install -e .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
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.exeAdd 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 availableUse an MCP connector or configure via your agent's settings. Example for a custom script:
python -m pixelorama_bridge.mcp_serverAdd 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 --mcp-server "python:-m:pixelorama_bridge.mcp_server"Adjust paths according to your system.
After configuring, restart your agent. The tools will be available once Pixelorama is running with the HermesBridge extension loaded.
Once connected, the agent has access to:
Tool | Description |
| Check if Pixelorama and HermesBridge extension are active |
| Launch Pixelorama (optionally with project) |
| Create transparent RGBA project with dimensions and frames |
| Open existing |
| Return dimensions, frame/layer counts |
| Replace cel with PNG (same size) |
| Export cel to PNG |
| Apply exact |
| Set frame duration multiplier |
| Save as |
| Export frames to transparent PNG spritesheet |
| Split spritesheet and import as real animation frames |
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=6Hermes-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 suiteMIT
This server cannot be deployed
Generate authentic pixel art - sprites, animations, and tilesets - from any MCP client
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
Generate AI images and videos from any compatible MCP client.
Generate AI images, video, music, and sound effects, and upscale them, from any MCP client.
