Pyxel MCP — MCP server for Claude Code: headless game runs
Runs a Pyxel game without a window, feeds scheduled button presses, and hands back screenshots, pixels and game state. Useful when an agent writes the game but cannot see the screen.
claude mcp add pyxel-mcp -- uvx pyxel-mcpWhat Pyxel MCP does
Each call starts the script in its own subprocess with dummy SDL drivers and a frame budget. Inputs are scheduled per frame, so a playtest becomes a JSON document you can rerun and extend. random_seed seeds Python's random and Pyxel's generator; other timing, randomness and outside state can still change what appears on screen.
You can end a run on an event rather than a fixed length: a condition such as until="score >= 1" stops the session on the first frame where that game attribute is true, and a "frame": "end" snapshot captures it. With inline: true, a PNG comes back as MCP image content, so the model sees the frame without an extra file read. There are eight tools: validate, run, pyxel_info, read_palette, read_image, read_tilemap, read_audio and diff_frames.
Python 3.11+ is required and Pyxel arrives as a dependency. The script argument takes a file path, not Python source; relative asset paths resolve from the script's directory. Subprocesses keep Pyxel state apart, yet they are not a sandbox, so untrusted code should not be run this way. Statements after pyxel.run() never execute.
What it helps with
- check that arrow keys move the player
- capture the frame where the score changes
- compare two PNG frames and list pixel differences
- inspect the palette and tilemap of a game
- export a Pyxel sound or music track as WAV
Example prompts for the agent
- Run
game.pyfor 600 frames with right held from frame 0, jump at frame 25, and stop once the score changes. - Validate
game.pyfor syntax errors and Pyxel patterns without running it. - Return frame 80 of the last run as an inline image in your answer.
How to install Pyxel MCP
Platform CLI
claude mcp add pyxel-mcp -- uvx pyxel-mcpuvx runs the command named after the package; if the README names another one, use uvx --from pyxel-mcp <command>
Platform CLI
codex mcp add pyxel-mcp -- uvx pyxel-mcpuvx runs the command named after the package; if the README names another one, use uvx --from pyxel-mcp <command>
Config file
{
"mcpServers": {
"pyxel-mcp": {
"command": "uvx",
"args": [
"pyxel-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from pyxel-mcp <command>
Config file
{
"servers": {
"pyxel-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"pyxel-mcp"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from pyxel-mcp <command>
Platform CLI
gemini mcp add pyxel-mcp uvx pyxel-mcpuvx runs the command named after the package; if the README names another one, use uvx --from pyxel-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Pyxel MCP
How do I install Pyxel MCP in Claude Code?
Run claude mcp add pyxel-mcp -- uvx pyxel-mcp and restart the client afterwards.
What does Pyxel MCP do?
It executes a Pyxel script headlessly, injects scripted input, and reports what happened: screenshots, pixel grids, state, assets, audio and frame diffs.
Which tools does the server expose?
validate, run, pyxel_info, read_palette, read_image, read_tilemap, read_audio and diff_frames. Every result carries ok and errors fields.
