MCP server for Pyxel, a retro game engine for Python
SaferSkills independently audited Pyxel MCP (MCP Server) and scored it 100/100 (green). The audit ran 55 deterministic rules across Security, Supply Chain, Maintenance, Transparency, and Community; it found 0 high-severity and 0 lower-severity findings. The full rule-by-rule trace and per-finding evidence are below. Free, methodology-open.
Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
MCP server for Pyxel, a retro game engine for Python. It gives AI agents a compact set of verbs to run and observe Pyxel programs without a window: headless, deterministic, and scriptable.
The server is deliberately an observation adapter. It does not judge whether a game is good. Agents use the returned state, pixels, audio, docs, and diffs to make task-specific decisions.
Tools that accept script execute trusted local Python. pyxel-mcp isolates Pyxel state per subprocess, but it is not a sandbox for untrusted code.
LLM agents writing Pyxel code without feedback often stop at "the script runs". pyxel-mcp closes that loop:
ok / errors fields.validate and resource readers expose common mistakes such as missing cls, missing colkey, tilemap (0, 0) traps, and ragged image rows.Register the published package as an MCP server in your client. The CLI prints the snippet:
uvx pyxel-mcp installThe printed snippet uses uvx pyxel-mcp, so it resolves the published package. For an unreleased checkout, point your MCP config at that checkout's console script or local Python environment instead.
Paste the printed JSON into your client's MCP config:
~/.claude/.mcp.json or per-project .mcp.json~/.cursor/mcp.json~/.codex/mcp.jsonSnippet:
{
"mcpServers": {
"pyxel": {
"command": "uvx",
"args": ["pyxel-mcp"]
}
}
}Restart your client. The server logs a startup line to stderr so you can confirm it loaded:
[pyxel-mcp] starting - 9 toolsPyxel >= 2.9.6 is installed as a dependency.
For workflow guidance, install the separate pyxel-skill repository. pyxel-mcp does not ship or publish skills.
| Tool | Purpose |
|---|---|
run | Drive N frames headlessly. Supports inputs plus screen_image, screen_grid, state, layout, and video snapshots. |
validate | Syntax and common Pyxel anti-pattern checks. |
pyxel_info | Version, path, example, and resource discovery. |
read_palette | Palette state, used indices, hierarchy hints, and contrast warnings. |
read_image | Image-bank region pixels and optional rendered PNG. |
read_animation | Adjacent sprite-frame consistency and per-pair diffs. |
read_tilemap | Tile usage, non-empty region, and (0, 0) trap warning. |
read_audio | Render a sound or music target to WAV and return duration, peak, notes, warnings. |
diff_frames | Pixel-wise diff between two PNG files. |
validate before the first dynamic run.run with a state snapshot and a screen_image at the frame being verified.read_* or diff_frames only when the task needs that specific observation.pyxel://run-snapshots-schema - full grammar for run.snapshots.pyxel://anti-patterns - validate issue catalog.pyxel://api-reference, pyxel://user-guide, pyxel://mml-commands, pyxel://pyxres-format - Pyxel docs.pyxel://palette/default - default palette table.pyxel://examples/<name> - bundled Pyxel examples.uvx caches packages. Force a refresh with:
uvx --refresh-package pyxel-mcp pyxel-mcp installTools do not appear. Look for [pyxel-mcp] starting - 9 tools in client logs, then restart the client if the config changed.
A script crashes on `pyxel.init()`. User scripts should call pyxel.init() once. Tool calls are isolated subprocesses, so repeated runs should go through pyxel-mcp rather than re-importing a script in the same process.
A validation issue is unfamiliar. Read pyxel://anti-patterns.
mcp-name: io.github.kitao/pyxel-mcp
MIT
~30 seconds. Free. No account. Every finding cites a rule and a line of evidence.