io.github.kitaoPublished by GitHub account kitaov1.3.2Updated Oct 25, 2026
MCP server for Pyxel, a retro game engine for Python
An MCP server that runs Pyxel retro game scripts headlessly, feeds them scheduled input, and returns screenshots, state, assets, audio and frame diffs.
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
Let AI agents play, watch, and measure Pyxel games. pyxel-mcp is an MCP server that runs a Pyxel script headlessly, feeds it scheduled input, stops when a condition holds, and hands back the facts: screenshots, pixel grids, game state, assets, audio, and frame diffs.
[PyPI] [Python] [Tests] [License] [MCP Registry]
[Pyxel's bundled platformer example driven headlessly with right held and three scheduled jumps] [Frame 80 of the same run at scale 3, returned inline as image content]
Both images come from one run call against Pyxel's bundled 10_platformer.py: 150 frames, right held from frame 0, jumps scheduled at frames 25, 70, and 110, a video snapshot, and an inline screen_image snapshot.
An agent can write a Pyxel game in seconds, but it cannot open a window, press the arrow keys, or look at the screen. Editor-bound engines solve this with MCP servers that live inside the editor. Pyxel has no editor process to attach to, so pyxel-mcp drives the game itself:
random_seed to seed Python's random module and Pyxel's random generator. Other randomness, timing, and external state can still affect the frames.until="score >= 1" ends the run at the first frame where a game attribute holds, and "frame": "end" snapshots capture that moment.inline: true returns a PNG as MCP image content, so the model looks at the screen without a second file read.Register the stdio server with your client:
For Cursor (~/.cursor/mcp.json), a project-scoped Claude Code .mcp.json, or any other client that reads the common JSON format, add:
VS Code uses .vscode/mcp.json with a top-level servers key and "type": "stdio"; Codex CLI can also be configured in ~/.codex/config.toml as [mcp_servers.pyxel]. Run uvx pyxel-mcp install to print every variant.
Claude Code users can instead install the pyxel-skill plugin, which registers this server together with the skill that teaches agents how to use it:
Restart the client after changing its configuration. The server writes this diagnostic to stderr:
Python 3.11+ is required, and Pyxel >= 2.9.6 is installed as a dependency. Script tools execute local Python in subprocesses to isolate Pyxel state, but they do not sandbox untrusted code. See SECURITY.md.
The loop is deliberately small. The separate pyxel-skill project teaches agents when to use each tool and what counts as enough evidence; this package only supplies the observations.
Every script argument is a file path, not Python source. Relative asset paths inside the script resolve from the script's directory, as when running python game.py from that directory.
All tools declare input and output schemas. Every result includes ok and errors.
Script tools observe the first pyxel.run() call while its enclosing resources
remain active. run drives the callbacks there; the asset readers inspect the
pre-loop state. pyxel.quit() ends a run normally and preserves completed
frames. Statements after pyxel.run() are not executed. Enclosing cleanup runs
after observation, and cleanup failures are reported with phase: "script_exit".
Stopping uses internal BaseException signals. Scripts or context-manager
cleanup that suppress these signals are unsupported and may execute post-run code.
Captured PNGs can travel inside the result: set inline: true on a screen_image snapshot, or inline=true on read_image and read_tilemap, and the PNG is returned as MCP image content next to the structured data. A single inline frame may omit its output path; the file is then written under the system temp directory and its path is still reported, so diff_frames and later comparisons keep working. At most 12 images are embedded per call.
Hold right, jump at frame 25, stop as soon as the score changes, and look at that frame:
The result reports until_met, the reached frame_count, the requested state values, the PNG path, and the PNG itself as image content. Artifact paths you choose must be absolute. Read log even when ok is true, and inspect captured images directly when appearance matters.
pyxel://run-snapshots-schema — complete run.snapshots grammar, including "end", ranges, and inline.pyxel://validation-patterns — categories reported by validate.pyxel://palette/default — default palette table.pyxel://examples/{name} — source for an example bundled with the installed Pyxel package; discover names with pyxel_info.uvx caches packages. Force a refresh with:
starting - 8 tools diagnostic and restart the client.run fails, inspect errors, exit_status, and log.pyxel://validation-patterns.mcp-name: io.github.kitao/pyxel-mcp
MIT — see LICENSE.
Source: README.md at commit e1b6b74
Run Pyxel script headlessly
Run a Pyxel script headlessly for a frame budget or until a condition holds, with scheduled input and state, screen, or video capture. screen_image snapshots with inline=true also return the PNG as image content, and a single inline frame may omit its output path.
untilframesrequiredinputsscriptrequiredtimeoutsnapshotsrandom_seedstall_window_framesValidate Pyxel script
Check Python syntax and report recognizable Pyxel code patterns.
scriptrequiredPyxel environment info
Report installed versions, paths, examples, and Pyxel resource URIs.
Takes no parameters.
Read Pyxel palette
Read the active Pyxel palette and the palette indices used by image banks.
scriptrequiredRead image bank region
Read palette-index pixels from a Pyxel image-bank region and optionally render it to PNG; inline=true returns the render as image content and makes render_path optional.
hwxyimagerequiredinlinescriptrequiredrender_pathRead tilemap
Read Pyxel tile coordinates, usage, bounds, source bank, and optional rendered output; inline=true returns the render as image content and makes render_path optional.
inlinescriptrequiredtilemaprequiredrender_pathRender audio to WAV
Render one Pyxel sound or music slot to WAV and return measurable audio data. Notes describe tracker fields, not an MML or PCM transcription.
scriptrequiredtargetrequiredoutput_pathrequiredDiff two frames
Compare two PNG frames pixel by pixel and return their changed region and ratio.
frame_arequiredframe_brequired90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
claude mcp add --scope user pyxel -- uvx pyxel-mcpcodex mcp add pyxel -- uvx pyxel-mcpgemini mcp add pyxel uvx pyxel-mcp { "mcpServers": { "pyxel": { "command": "uvx", "args": ["pyxel-mcp"] } } }claude plugin marketplace add kitao/pyxel-skill && claude plugin install pyxel@pyxel-skill[pyxel-mcp] starting - 8 toolsflowchart LR W["Write or edit<br>game.py"] --> V["validate"] V --> R["run<br>inputs · until · snapshots"] R --> O{"Inspect facts<br>state · pixels · log"} O -- "defect" --> W O -- "looks right" --> A["read_image · read_tilemap<br>read_audio · diff_frames"] A --> D["Report evidence"]{ "script": "/absolute/path/game.py", "frames": 600, "random_seed": 7, "inputs": [ {"frame": 0, "buttons": ["KEY_RIGHT"]}, {"frame": 25, "buttons": ["KEY_RIGHT", "KEY_SPACE"]}, {"frame": 26, "buttons": ["KEY_RIGHT"]} ], "until": "score >= 1", "snapshots": [ {"kind": "state", "frame": "end", "attrs": ["score", "player.x"]}, {"kind": "screen_image", "frame": "end", "scale": 3, "inline": true} ]}uvx --refresh-package pyxel-mcp pyxel-mcp install