Pyxel MCP
MCP server for Pyxel, a retro game engine for Python
Open source Open in the app JSON README (API)
About
MCP server for Pyxel, a retro game engine for Python
Details
- Kind
- MCP servers
- Topic
- Media, design & games
- Publisher
- kitao
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.2.0
- Stars
- 26
- Forks
- 3
- Last push
- 2026-07-15T10:05:51Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:21
- Updated
- 2026-08-29 04:00:21
- Origin id
io.github.kitao/pyxel-mcp
README
# pyxel-mcp
An MCP server for observing programs built with [Pyxel](https://github.com/kitao/pyxel). It runs trusted local scripts headlessly and returns structured state, pixels, assets, audio, and frame differences.
[](https://pypi.org/project/pyxel-mcp/)
[](https://pypi.org/project/pyxel-mcp/)
[](https://github.com/kitao/pyxel-mcp/actions/workflows/test.yml)
[](LICENSE)
[](https://registry.modelcontextprotocol.io)
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:
```bash
claude mcp add pyxel -- uvx pyxel-mcp
```
For another MCP client, run `uvx pyxel-mcp install` or add:
```json
{
"mcpServers": {
"pyxel": {
"command": "uvx",
"args": ["pyxel-mcp"]
}
}
}
```
Restart the client after changing its configuration. The server writes this diagnostic to stderr:
```text
[pyxel-mcp] starting - 8 tools
```
Python 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](SECURITY.md).
## Tools
Every `script` argument is a file path, not Python source.
| Tool | Returns |
|---|---|
| `validate` | Syntax errors and recognizable Pyxel code patterns. |
| `run` | Headless frames, scheduled input, logs, and `state`, `screen_image`, `screen_grid`, or `video` snapshots. |
| `pyxel_info` | Installed versions, paths, examples, and resource URIs. |
| `read_palette` | Palette colors and image-bank indices in use. |
| `read_image` | Image-bank pixels and an optional PNG render. |
| `read_tilemap` | Tile coordinates, source bank, usage counts, bounds, and an optional render. |
| `read_audio` | A rendered sound or music WAV plus measurable audio data. |
| `diff_frames` | 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:
```json
{
"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` — complete `run.snapshots` grammar.
- `pyxel://validation-patterns` — categories reported by `validate`.
- `pyxel://palette/default` — default palette table.
- `pyxel://examples/{name}` — source for an example bundled with the installed Pyxel package; discover names with `pyxel_info`.
Full game-building guidance lives in the separate [pyxel-skill](https://github.com/kitao/pyxel-skill) project; this package contains only the MCP server.
## Update
`uvx` caches packages. Force a refresh with:
```bash
uvx --refresh-package pyxel-mcp pyxel-mcp install
```
## Troubleshooting
- If tools do not appear, look for the `starting - 8 tools` diagnostic and restart the client.
- If `run` fails, inspect `errors`, `exit_status`, and `log`.
- If a validation category is unfamiliar, read `pyxel://validation-patterns`.
## MCP Registry
`mcp-name: io.github.kitao/pyxel-mcp`
## License
MIT — see [LICENSE](LICENSE).