pyxel-mcp
pyxel-mcp is an MCP server for the Pyxel retro game engine that enables AI agents to autonomously run, verify, debug, and iterate on retro game programs written in Python.
Run & Capture
Run a Pyxel script and capture a screenshot after a specified number of frames
Capture screenshots at multiple frame points to verify animations
Record frames as a GIF for animation/transition verification
Simulate keyboard/mouse input at specific frames and capture screenshots to test input-dependent logic
Inspect & Debug
Validate a Pyxel script via AST parsing without running it (syntax errors and anti-patterns)
Read game object attributes at specific frames for debugging, with multi-frame diff support
Capture the screen as a compact color index grid for programmatic analysis
Compare screenshots at two frames to report pixel differences and changed regions (visual regression testing)
Visual Analysis
Inspect sprite pixel data from a Pyxel image bank, including symmetry and color usage
Analyze screen layout, text alignment, centering, and visual balance
Analyze color usage, distribution, background color, and contrast issues
Visualize an entire 256×256 Pyxel image bank as a screenshot
Inspect tilemap content, tile usage statistics, and layout
Check sprite sheet consistency across animation frames
Audio
Render a Pyxel sound or music track to WAV and return waveform analysis (note sequence, timing, frequency, volume)
Utility
Retrieve Pyxel installation info: package location, examples path, and API stubs path
Resources
Access official Pyxel API reference, user guide, MML commands, and pyxres format
Browse official Pyxel example programs and the default 16-color palette
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 "Install 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-mcpRun 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
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 verificationrecord_gameplay— Record N frames as a GIF for animation/transition 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 layoutinspect_animation— Check sprite sheet consistency across animation frames
Audio
render_audio— Render a Pyxel sound or music to WAV and return waveform analysis
Resources (Pyxel reference)
In addition to tools, the server exposes Pyxel reference content as MCP Resources:
pyxel://api-reference,pyxel://user-guide,pyxel://mml-commands,pyxel://pyxres-format— official Pyxel docspyxel://examples/<name>— official Pyxel examples (e.g.02_jump_game)pyxel://palette/default— 16-color palette with use hints
In Claude Code, reference them with @pyxel:examples/02_jump_game etc.
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-mcpRegister
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
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Latest Blog Posts
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kitao/pyxel-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server