# Pyxel MCP

Runs a Pyxel game without a window, feeds scheduled button presses, and hands back screenshots, pixels and game state. Useful when an agent writes the game but cannot see the screen.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 30
- Author: kitao
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/kitao/pyxel-mcp
- Updated: 2026-10-23
- HTML: https://affpapa.org/en/nevibecode/mcp/pyxel-mcp

## What it does

Each call starts the script in its own subprocess with dummy SDL drivers and a frame budget. Inputs are scheduled per frame, so a playtest becomes a JSON document you can rerun and extend. `random_seed` seeds Python's `random` and Pyxel's generator; other timing, randomness and outside state can still change what appears on screen.

You can end a run on an event rather than a fixed length: a condition such as `until="score >= 1"` stops the session on the first frame where that game attribute is true, and a `"frame": "end"` snapshot captures it. With `inline: true`, a PNG comes back as MCP image content, so the model sees the frame without an extra file read. There are eight tools: `validate`, `run`, `pyxel_info`, `read_palette`, `read_image`, `read_tilemap`, `read_audio` and `diff_frames`.

Python 3.11+ is required and Pyxel arrives as a dependency. The `script` argument takes a file path, not Python source; relative asset paths resolve from the script's directory. Subprocesses keep Pyxel state apart, yet they are not a sandbox, so untrusted code should not be run this way. Statements after `pyxel.run()` never execute.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add pyxel-mcp -- uvx pyxel-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from pyxel-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add pyxel-mcp -- uvx pyxel-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from pyxel-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "pyxel-mcp": {
            "command": "uvx",
            "args": [
                "pyxel-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from pyxel-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "pyxel-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "pyxel-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from pyxel-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add pyxel-mcp uvx pyxel-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from pyxel-mcp <command>

## When to use it
- check that arrow keys move the player
- capture the frame where the score changes
- compare two PNG frames and list pixel differences
- inspect the palette and tilemap of a game
- export a Pyxel sound or music track as WAV

## Example prompts
- Run `game.py` for 600 frames with right held from frame 0, jump at frame 25, and stop once the score changes.
- Validate `game.py` for syntax errors and Pyxel patterns without running it.
- Return frame 80 of the last run as an inline image in your answer.

## Similar
- [Pascal 3D Editor](https://affpapa.org/en/nevibecode/mcp/pascal-3d-editor.md) — MCP server · ★ 25085
- [Unity-MCP](https://affpapa.org/en/nevibecode/mcp/unity-mcp.md) — MCP server · ★ 4523
- [mcp](https://affpapa.org/en/nevibecode/mcp/sceneview-mcp.md) — MCP server · ★ 1348
- [Gearboy MCP Server](https://affpapa.org/en/nevibecode/mcp/gearboy-mcp-server.md) — MCP server · ★ 1219
- [ChiR24-unreal_mcp_server](https://affpapa.org/en/nevibecode/mcp/chir24-unreal-mcp-server.md) — MCP server · ★ 975
- [Nova3D](https://affpapa.org/en/nevibecode/mcp/nova3d.md) — MCP server · ★ 733

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md