Pyxel MCP

What kitao/pyxel-mcp MCP server does

The kitao/pyxel-mcp MCP server gives an MCP client structured access to programs built with the Pyxel retro game engine. It runs local Pyxel scripts without opening the normal interactive display, then returns execution details, captured state, pixels, assets, audio data, or image differences. The server reports observations and test results; it does not assign a universal quality score to a game.

Each script input is a filesystem path to a Python file, not an inline source string. Results include an ok field and an errors field, which lets a client distinguish successful execution from reported problems. Captured artifacts should use absolute paths.

How it works

Script-based operations launch local Python subprocesses, which isolates Pyxel state between executions. The run tool can process a fixed number of frames or stop when a supplied condition becomes true. It supports scheduled input and can capture attributes from program state, rendered screen output, screen grids, or video. Logs remain important even when the result reports success, because runtime details are returned separately.

The other tools inspect Pyxel data or previously created files. Palette and image tools work with indexed Pyxel graphics, while tilemap inspection reports tile coordinates, source image banks, usage counts, and bounds. Audio inspection renders a selected sound or music slot to WAV and returns measurable audio information. Frame comparison examines two PNG files pixel by pixel and reports the changed area and change ratio.

Setup and configuration

Install the kitao/pyxel-mcp MCP server with uvx:

uvx pyxel-mcp install

For a client configuration that accepts stdio servers, use uvx as the command and pyxel-mcp as its argument. Claude Code is shown as a supported setup path in the project documentation. Restart the MCP client after changing its configuration. On startup, the server writes a diagnostic such as starting - 8 tools to stderr.

Python 3.11 or later is required. Pyxel 2.9.6 or later is installed as a dependency. The package uses cached uvx packages; uvx --refresh-package pyxel-mcp pyxel-mcp install forces a package refresh.

The server also exposes resources for the snapshot grammar, validation categories, the default palette, and bundled Pyxel example source. Example names can be discovered through pyxel_info.

Tools and capabilities

The kitao/pyxel-mcp MCP server exposes these tools:

• run: Execute a script headlessly with a frame budget or stopping condition, scheduled input, logs, and optional snapshots.
• validate: Check Python syntax and report recognizable Pyxel code patterns.
• pyxel_info: Return installed versions, paths, examples, and Pyxel resource URIs.
• read_palette: Report palette colors and the indices used by image banks.
• read_image: Read indexed pixels from an image-bank region and optionally render a PNG.
• read_tilemap: Read tile coordinates, source banks, usage, bounds, and optional rendered output.
• read_audio: Render a sound or music slot to WAV and return measurable audio data.
• diff_frames: Compare two PNG frames and return pixel changes, the changed region, and a ratio.

Limitations and notes

The subprocess approach isolates Pyxel state but does not sandbox untrusted code. Only run scripts that are trusted in the local environment. The package contains the MCP server, not the separate Pyxel game-building guidance project. If tools do not appear, check the startup diagnostic and restart the client. When run fails, inspect errors, exit_status, and log; when visual appearance matters, inspect captured images directly.