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_and_capture — Run a Pyxel script and capture a screenshot after N frames
capture_frames — Capture screenshots at multiple frame points for animation verification
record_gameplay — Record N frames as a GIF for animation/transition verification
play_and_capture — Play a game by sending simulated input and capture screenshots

validate_script — Validate a Pyxel script without running it
inspect_state — Read game object attributes at specific frames for debugging
inspect_screen — Capture screen as a compact color index grid
compare_frames — Compare screenshots at two frames and report pixel differences

inspect_sprite — Inspect sprite pixel data from a Pyxel image bank
inspect_layout — Analyze screen layout, text alignment, and visual balance
inspect_palette — Analyze color usage and contrast in a Pyxel screenshot
inspect_bank — Visualize an entire Pyxel image bank as a single screenshot
inspect_tilemap — Inspect tilemap content, tile usage, and layout
inspect_animation — Check sprite sheet consistency across animation frames

render_audio — Render a Pyxel sound or music to WAV and return waveform analysis

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 docs
pyxel://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.

pyxel_info — Get Pyxel installation info: package location, examples path, and API stubs path

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.

hljs language-bash

pip install pyxel-mcp

hljs language-json

{
  "mcpServers": {
    "pyxel": {
      "type": "stdio",
      "command": "pyxel-mcp"
    }
  }
}

mcp-name: io.github.kitao/pyxel-mcp

MIT