# kitao/pyxel-mcp [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/kitao/pyxel-mcp  
**GitHub Stars:** 26  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/kitao-pyxel-mcp

## Description
MCP server for Pyxel retro game engine, enabling AI to run, capture screenshots, inspect sprites, and analyze audio of Pyxel games.

## Tools
Capabilities this server exposes over MCP:

- **run** — Run a Pyxel script headlessly for a frame budget or until a condition holds, with scheduled input and state, screen, or video capture.
- **validate** — Check Python syntax and report recognizable Pyxel code patterns.
- **pyxel_info** — Report installed versions, paths, examples, and Pyxel resource URIs.
- **read_palette** — Read the active Pyxel palette and the palette indices used by image banks.
- **read_image** — Read palette-index pixels from a Pyxel image-bank region and optionally render it to PNG.
- **read_tilemap** — Read Pyxel tile coordinates, usage, bounds, source bank, and optional rendered output.
- **read_audio** — Render one Pyxel sound or music slot to WAV and return measurable audio data.
- **diff_frames** — Compare two PNG frames pixel by pixel and return their changed region and ratio.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "pyxel-mcp": {
    "command": "uvx",
    "args": ["pyxel-mcp"]
  }
}
```

## Documentation

## What kitao/pyxel-mcp MCP server does

The kitao/pyxel-mcp MCP server gives an MCP client structured access to programs built with the Pyxel retro game engine. It runs local Pyxel scripts without opening the normal interactive display, then returns execution details, captured state, pixels, assets, audio data, or image differences. The server reports observations and test results; it does not assign a universal quality score to a game.

Each script input is a filesystem path to a Python file, not an inline source string. Results include an `ok` field and an `errors` field, which lets a client distinguish successful execution from reported problems. Captured artifacts should use absolute paths.

## How it works

Script-based operations launch local Python subprocesses, which isolates Pyxel state between executions. The `run` tool can process a fixed number of frames or stop when a supplied condition becomes true. It supports scheduled input and can capture attributes from program state, rendered screen output, screen grids, or video. Logs remain important even when the result reports success, because runtime details are returned separately.

The other tools inspect Pyxel data or previously created files. Palette and image tools work with indexed Pyxel graphics, while tilemap inspection reports tile coordinates, source image banks, usage counts, and bounds. Audio inspection renders a selected sound or music slot to WAV and returns measurable audio information. Frame comparison examines two PNG files pixel by pixel and reports the changed area and change ratio.

## Setup and configuration

Install the kitao/pyxel-mcp MCP server with `uvx`:

```bash
uvx pyxel-mcp install
```

For a client configuration that accepts stdio servers, use `uvx` as the command and `pyxel-mcp` as its argument. Claude Code is shown as a supported setup path in the project documentation. Restart the MCP client after changing its configuration. On startup, the server writes a diagnostic such as `starting - 8 tools` to stderr.

Python 3.11 or later is required. Pyxel 2.9.6 or later is installed as a dependency. The package uses cached `uvx` packages; `uvx --refresh-package pyxel-mcp pyxel-mcp install` forces a package refresh.

The server also exposes resources for the snapshot grammar, validation categories, the default palette, and bundled Pyxel example source. Example names can be discovered through `pyxel_info`.

## Tools and capabilities

The kitao/pyxel-mcp MCP server exposes these tools:

- `run`: Execute a script headlessly with a frame budget or stopping condition, scheduled input, logs, and optional snapshots.
- `validate`: Check Python syntax and report recognizable Pyxel code patterns.
- `pyxel_info`: Return installed versions, paths, examples, and Pyxel resource URIs.
- `read_palette`: Report palette colors and the indices used by image banks.
- `read_image`: Read indexed pixels from an image-bank region and optionally render a PNG.
- `read_tilemap`: Read tile coordinates, source banks, usage, bounds, and optional rendered output.
- `read_audio`: Render a sound or music slot to WAV and return measurable audio data.
- `diff_frames`: Compare two PNG frames and return pixel changes, the changed region, and a ratio.

## Limitations and notes

The subprocess approach isolates Pyxel state but does not sandbox untrusted code. Only run scripts that are trusted in the local environment. The package contains the MCP server, not the separate Pyxel game-building guidance project. If tools do not appear, check the startup diagnostic and restart the client. When `run` fails, inspect `errors`, `exit_status`, and `log`; when visual appearance matters, inspect captured images directly.

_Full upstream README: https://allmcps.com/mcp/kitao-pyxel-mcp/readme_