README.md
MCP server for the Pyxel retro game engine
pyxel-mcp
MCP server for Pyxel, a retro game engine for Python. Enables AI to autonomously run, verify, and iterate on retro game programs.
Features
Run & Capture
run_and_capture— Run a Pyxel script and capture a screenshot after N framescapture_frames— Capture screenshots at multiple frame points for animation verificationplay_and_capture— Play a game by sending simulated input and capture screenshots
Inspect & Debug
validate_script— Validate a Pyxel script without running itinspect_state— Read game object attributes at specific frames for debugginginspect_screen— Capture screen as a compact color index gridcompare_frames— Compare screenshots at two frames and report pixel differences
Visual Analysis
inspect_sprite— Inspect sprite pixel data from a Pyxel image bankinspect_layout— Analyze screen layout, text alignment, and visual balanceinspect_palette— Analyze color usage and contrast in a Pyxel screenshotinspect_bank— Visualize an entire Pyxel image bank as a single screenshotinspect_tilemap— Inspect tilemap content, tile usage, and layout
Audio
render_audio— Render a Pyxel sound or music to WAV and return waveform analysis
Utility
pyxel_info— Get Pyxel installation info: package location, examples path, and API stubs path
Getting Started
Just ask your AI agent (e.g. Claude Code) to create a Pyxel game. The agent will automatically discover and set up pyxel-mcp from the MCP Registry.
Manual Installation
- Install the package:
pip install pyxel-mcp
- Register
pyxel-mcpas an MCP server in your AI agent. For Claude Code, add to your project's.mcp.json:
{
"mcpServers": {
"pyxel": {
"type": "stdio",
"command": "pyxel-mcp"
}
}
}
MCP Registry
mcp-name: io.github.kitao/pyxel-mcp
License
MIT
Tools (14)
run_and_captureRun a Pyxel script and capture a screenshot after N framescapture_framesCapture screenshots at multiple frame points for animation verificationplay_and_capturePlay a game by sending simulated input and capture screenshotsvalidate_scriptValidate a Pyxel script without running itinspect_stateRead game object attributes at specific frames for debugginginspect_screenCapture screen as a compact color index gridcompare_framesCompare screenshots at two frames and report pixel differencesinspect_spriteInspect sprite pixel data from a Pyxel image bankinspect_layoutAnalyze screen layout, text alignment, and visual balanceinspect_paletteAnalyze color usage and contrast in a Pyxel screenshotinspect_bankVisualize an entire Pyxel image bank as a single screenshotinspect_tilemapInspect tilemap content, tile usage, and layoutrender_audioRender a Pyxel sound or music to WAV and return waveform analysispyxel_infoGet Pyxel installation info: package location, examples path, and API stubs pathConfiguration
claude_desktop_config.json
{"mcpServers": {"pyxel": {"type": "stdio", "command": "pyxel-mcp"}}}Try it
→Create a simple Pyxel game script that displays a moving square and verify it runs correctly.
→Inspect the current game state at frame 60 to debug why the player character is not jumping.
→Analyze the screen layout of my current Pyxel game to ensure the text is properly aligned.
→Render the audio for my game's background music and check the waveform analysis.