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
An MCP server for observing programs built with Pyxel. It runs trusted local scripts headlessly and returns structured state, pixels, assets, audio, and frame differences.
The server deliberately reports facts rather than a universal quality score. The agent using it chooses the checks that matter for the game.
Install
With Claude Code:
claude mcp add pyxel -- uvx pyxel-mcpFor another MCP client, run uvx pyxel-mcp install or add:
{
"mcpServers": {
"pyxel": {
"command": "uvx",
"args": ["pyxel-mcp"]
}
}
}Restart 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.
Related MCP server: aseprite-mcp
Tools
Every script argument is a file path, not Python source.
Tool | Returns |
| Syntax errors and recognizable Pyxel code patterns. |
| Headless frames, scheduled input, logs, and |
| Installed versions, paths, 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.
Example
Capture state and the screen when a condition first becomes true:
{
"script": "/absolute/path/game.py",
"frames": 600,
"until": "score >= 1",
"snapshots": [
{"kind": "state", "frame": "end", "attrs": ["score", "player.x"]},
{"kind": "screen_image", "frame": "end", "output": "/tmp/goal.png"}
]
}Use absolute artifact paths. Read log even when ok is true, and inspect captured images directly when appearance matters.
Resources
pyxel://run-snapshots-schema— completerun.snapshotsgrammar.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.
Full game-building guidance lives in the separate pyxel-skill project; this package contains only the MCP server.
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 validation category is unfamiliar, read
pyxel://validation-patterns.
MCP Registry
mcp-name: io.github.kitao/pyxel-mcp
License
MIT — see LICENSE.
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
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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