pyxel-mcp

Overview

Pyxel-MCP is a specialized MCP server that enables AI agents to autonomously develop, test, and analyze retro games using Pyxel, a Python-based retro game engine. It provides comprehensive tools for running game scripts, capturing screenshots, recording gameplay, and debugging game state. The server also exposes Pyxel reference documentation as MCP resources, making it easier for AI agents to access official documentation and examples during development.

Try asking AI

After installing, here are 5 things you can ask your AI assistant:

• run_and_capture

  Run a Pyxel script and capture a screenshot after N frames

  Try:Run my game and capture a screenshot after 60 frames
• capture_frames

  Capture screenshots at multiple frame points for animation verification

  Try:Capture frames 10, 20, and 30 of my animation
• record_gameplay

  Record N frames as a GIF for animation/transition verification

  Try:Record 30 frames of gameplay as a GIF
• play_and_capture

  Play a game by sending simulated input and capture screenshots

  Try:Play my game with right arrow key pressed and capture a screenshot
• validate_script

  Validate a Pyxel script without running it

  Try:Check if my Pyxel script has any syntax errors
• inspect_state

  Read game object attributes at specific frames for debugging

  Try:Show the player position at frame 45
• inspect_screen

  Capture screen as a compact color index grid

  Try:Show the current screen as a color grid
• compare_frames

  Compare screenshots at two frames and report pixel differences

  Try:Compare frames 10 and 20 to see what changed
• inspect_sprite

  Inspect sprite pixel data from a Pyxel image bank

  Try:Show me the pixel data for sprite #5
• inspect_layout

  Analyze screen layout, text alignment, and visual balance

  Try:Check if my UI elements are well balanced
• inspect_palette

  Analyze color usage and contrast in a Pyxel screenshot

  Try:Analyze the color palette of my game screen
• render_audio

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

  Try:Render my background music to WAV and show the waveform

Comparable tools

Installation

pip install pyxel-mcp

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

FAQ

What is Pyxel?

Pyxel is a retro game engine for Python, inspired by PICO-8, designed for creating small retro-style games.

How can I access the Pyxel examples through this MCP server?

You can reference examples using the format `@pyxel:examples/<name>` in Claude Code, such as `@pyxel:examples/02_jump_game`.

Compare pyxel-mcp with