pyxel-mcp
pyxel-mcp lets AI agents drive Pyxel games headlessly and inspect the results with screenshots, pixel grids, state, audio, and diffs.
Run a Pyxel script headlessly for a frame budget, with scheduled button/axis/mouse inputs, random seeding, a stop condition (
until), and timeouts/stall detection.Capture snapshots at specific frames or at the end: game state attributes, screen images (PNG, optionally inline as image content), pixel grids, and video (GIF/MP4).
Validate Pyxel scripts for syntax and recognizable Pyxel patterns without executing them.
Get environment info: installed versions, paths, bundled examples, and Pyxel resource URIs.
Read palette colors and which palette indices are used by image banks.
Read image-bank regions as pixel arrays and optionally render them to PNG inline.
Read tilemaps: tile coordinates, usage counts, bounds, source bank, and optional rendered output.
Render sound or music slots to WAV and get measurable audio data like duration, sample rate, peak amplitude, and notes.
Compare two PNG frames pixel by pixel to report changed region, changed pixel count, ratio, and whether they are identical.
Enables AI to autonomously run, verify, and iterate on retro game programs created with the Pyxel engine, providing tools for Python script validation, state inspection, and visual/audio analysis.
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., "@pyxel-mcp Run main.py and capture a screenshot to verify the game visuals"
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.
pyxel-mcp
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.
Why
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:
Headless execution. Every call runs the script in a fresh subprocess with SDL dummy drivers and a frame budget. Set
random_seedto seed Python'srandommodule and Pyxel's random generator. Other randomness, timing, and external state can still affect the frames.Input as data. Buttons, axes, and mouse position are scheduled per frame, so a playtest is a JSON document the agent can rerun and extend.
Stop on the event, not the clock.
until="score >= 1"ends the run at the first frame where a game attribute holds, and"frame": "end"snapshots capture that moment.Facts, not scores. Tools report pixels, values, and measurements. Deciding whether the game is good stays with the agent and the person asking for it.
See the frame in the result.
inline: truereturns a PNG as MCP image content, so the model looks at the screen without a second file read.
Related MCP server: Aseprite MCP
Install
Register the stdio server with your client:
claude mcp add --scope user pyxel -- uvx pyxel-mcpcodex mcp add pyxel -- uvx pyxel-mcpgemini mcp add pyxel uvx pyxel-mcpFor Cursor (~/.cursor/mcp.json), a project-scoped Claude Code .mcp.json, or any other client that reads the common JSON format, add:
{
"mcpServers": {
"pyxel": {
"command": "uvx",
"args": ["pyxel-mcp"]
}
}
}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:
claude plugin marketplace add kitao/pyxel-skill && claude plugin install pyxel@pyxel-skillRestart the client after changing its configuration. The server writes this diagnostic to stderr:
[pyxel-mcp] starting - 8 toolsPython 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.
How an agent uses it
flowchart 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"]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.
Tools
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.
Tool | Returns |
| Syntax errors and recognizable Pyxel code patterns, without executing. |
| Headless frames, scheduled input, logs, and |
| Installed versions, paths, bundled examples, and resource URIs. |
| Palette colors and image-bank indices in use. |
| Image-bank pixels and an optional PNG render. |
| Tile coordinates, source bank, usage counts, bounds, and an optional render. |
| A rendered sound or music WAV plus measurable audio data. |
| Pixel differences between two PNG files. |
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.
Example
Hold right, jump at frame 25, stop as soon as the score changes, and look at that frame:
{
"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}
]
}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.
Resources
pyxel://run-snapshots-schema— completerun.snapshotsgrammar, including"end", ranges, andinline.pyxel://validation-patterns— categories reported byvalidate.pyxel://palette/default— default palette table.pyxel://examples/{name}— source for an example bundled with the installed Pyxel package; discover names withpyxel_info.
Update
uvx caches packages. Force a refresh with:
uvx --refresh-package pyxel-mcp pyxel-mcp installTroubleshooting
If tools do not appear, look for the
starting - 8 toolsdiagnostic and restart the client.If
runfails, inspecterrors,exit_status, andlog.If a script cannot find an asset, check the path relative to the script file, not to the client's working directory.
If a validation category is unfamiliar, read
pyxel://validation-patterns.
Related
Pyxel — the retro game engine this server observes.
pyxel-skill — the Agent Skill that turns these tools into a build-and-verify workflow.
CHANGELOG.md — what changed in each release.
MCP Registry
mcp-name: io.github.kitao/pyxel-mcp
License
MIT — see LICENSE.
Available Tools
8 toolsdiff_framesARead-onlyIdempotent
Compare two PNG frames pixel by pixel and return their changed region and ratio.
Inputs: frame_a (required), frame_b (required). Returns: ok, ratio, errors, region, +7 more
pyxel_infoARead-onlyIdempotent
Report installed versions, paths, examples, and Pyxel resource URIs.
Inputs: no named parameters. Returns: ok, errors, examples, resources, +4 more
read_audioA
Render one Pyxel sound or music slot to WAV and return measurable audio data. Notes describe tracker fields, not an MML or PCM transcription.
Inputs: script (required), target (required), output_path (required). Returns: ok, path, notes, errors, +5 more
read_imageA
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.
Inputs: image (required), script (required), h, w, +4 more. Returns: ok, errors, pixels, region, +4 more
read_paletteC
Read the active Pyxel palette and the palette indices used by image banks.
Inputs: script (required). Returns: ok, colors, errors, palette_size, +2 more
read_tilemapA
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.
Inputs: script (required), tilemap (required), inline, render_path. Returns: ok, size, tiles, usage, +7 more
runA
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.
Inputs: frames (required), script (required), until, inputs, +4 more. Returns: ok, log, errors, seeded, +5 more
validateARead-onlyIdempotent
Check Python syntax and report recognizable Pyxel code patterns.
Inputs: script (required). Returns: ok, errors, issues
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool maps to a distinct concern: environment info, script execution, audio rendering, frame comparison, and specific resource readers for images, palettes, and tilemaps. Even the read_* tools are cleanly separated by resource type, so there is no meaningful overlap between them.
Most tools follow a clear action_resource pattern, especially read_image, read_palette, read_tilemap, and read_audio. The deviations are minor: pyxel_info is noun-ish and run is a bare verb, but both are still understandable and do not undermine the overall scheme.
With 8 tools, the surface is tightly scoped to running Pyxel scripts and inspecting Pyxel resources and output. No tool feels redundant or out of place, and the count is well within the ideal range.
The server covers a coherent inspect-and-run workflow: validate scripts, execute them, capture frames, diff frames, and read images, palettes, tilemaps, and audio. The main gap is the lack of tools for creating or modifying Pyxel resources, which is a workaround if the server is intended as a read-only/testing interface.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Generate authentic pixel art - sprites, animations, and tilesets - from any MCP client
MCP server for building and testing AI agents with multi-model experimentation and insights.
Generate game-ready 3D models, textures, and audio from natural language, over MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for programmatically creating and editing Aseprite sprites, enabling AI agents to draw, manage layers and frames, and iterate until the desired result is achieved.MIT
- AlicenseBqualityBmaintenanceAn MCP server that lets AI agents create and edit Aseprite sprites headlessly, enabling pixel art, animation, and export via 98 tools.15641MIT
- FlicenseAqualityDmaintenanceAn MCP server that enables AI coding agents to create pixel art programmatically by providing canvas manipulation tools and PNG export.1031 npm9-
- AlicenseNot gradedqualityCmaintenanceAn AI-native game engine MCP server that enables AI agents to create, modify, and run games using 53 tools for scene creation, physics, audio, 3D rendering, and AI-generated images and music.1MIT