Pyxel MCP

19STDIOregistry active

Summary

This connects Claude to Pyxel, the retro game engine for Python, letting the AI write games and verify they actually work through visual feedback. You get tools to run scripts and capture screenshots at specific frames, record gameplay as GIFs, simulate player input, and inspect sprites, tilemaps, and color palettes pixel by pixel. It also exposes Pyxel's API docs and example games as MCP resources so Claude can reference them directly. Reach for this when you want an AI coding assistant that can iterate on game code by seeing what it renders, not just hoping the syntax is right.

CodeRabbit

AI writes the code. CodeRabbit catches the slop.

Try For Free →

inference shell

create and run specialised agents in minutes

build now →

MCP-ready Email Sending

Plug Mailtrap into your AI workflow and let it handle the email.

Connect Mailtrap MCP →

Make your agent a DeFi expert

Agent, run crypto. Access onchain data & trade routes via 1inch.

Install now →

Capacitor - Shared memory for your team’s coding agents.

Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.

Try For Free →

CodeScene MCP Server

Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.

Try For Free →

Give your AI the whole web as clean markdown

Integrate web data into your AI product. One API to scrape website & brand data.

Get API Key Now →

belt - the only tool your agent needs

belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...

one prompt install →

CodeRabbit

AI writes the code. CodeRabbit catches the slop.

Try For Free →

inference shell

create and run specialised agents in minutes

build now →

MCP-ready Email Sending

Plug Mailtrap into your AI workflow and let it handle the email.

Connect Mailtrap MCP →

Make your agent a DeFi expert

Agent, run crypto. Access onchain data & trade routes via 1inch.

Install now →

Capacitor - Shared memory for your team’s coding agents.

Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.

Try For Free →

CodeScene MCP Server

Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.

Try For Free →

Give your AI the whole web as clean markdown

Integrate web data into your AI product. One API to scrape website & brand data.

Get API Key Now →

belt - the only tool your agent needs

belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...

one prompt install →

pyxel-mcp

An MCP server for observing programs built with Pyxel. It runs trusted local scripts headlessly and returns structured state, pixels, assets, audio, and frame differences.

The server deliberately reports facts rather than a universal quality score. The agent using it chooses the checks that matter for the game.

Install

With Claude Code:

claude mcp add pyxel -- uvx pyxel-mcp

For another MCP client, run uvx pyxel-mcp install or add:

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

Restart the client after changing its configuration. The server writes this diagnostic to stderr:

[pyxel-mcp] starting - 8 tools

Python 3.11+ is required, and Pyxel >= 2.9.6 is installed as a dependency. Script tools execute local Python in subprocesses to isolate Pyxel state, but they do not sandbox untrusted code. See SECURITY.md.

Tools

Every script argument is a file path, not Python source.

Tool	Returns
`validate`	Syntax errors and recognizable Pyxel code patterns.
`run`	Headless frames, scheduled input, logs, and `state`, `screen_image`, `screen_grid`, or `video` snapshots.
`pyxel_info`	Installed versions, paths, examples, and resource URIs.
`read_palette`	Palette colors and image-bank indices in use.
`read_image`	Image-bank pixels and an optional PNG render.
`read_tilemap`	Tile coordinates, source bank, usage counts, bounds, and an optional render.
`read_audio`	A rendered sound or music WAV plus measurable audio data.
`diff_frames`	Pixel differences between two PNG files.

All tools declare input and output schemas. Every result includes ok and errors.

Example

Capture state and the screen when a condition first becomes true:

{
  "script": "/absolute/path/game.py",
  "frames": 600,
  "until": "score >= 1",
  "snapshots": [
    {"kind": "state", "frame": "end", "attrs": ["score", "player.x"]},
    {"kind": "screen_image", "frame": "end", "output": "/tmp/goal.png"}
  ]
}

Use absolute artifact paths. Read log even when ok is true, and inspect captured images directly when appearance matters.

Resources

pyxel://run-snapshots-schema — complete run.snapshots grammar.
pyxel://validation-patterns — categories reported by validate.
pyxel://palette/default — default palette table.
pyxel://examples/{name} — source for an example bundled with the installed Pyxel package; discover names with pyxel_info.

Full game-building guidance lives in the separate pyxel-skill project; this package contains only the MCP server.

Update

uvx caches packages. Force a refresh with:

uvx --refresh-package pyxel-mcp pyxel-mcp install

Troubleshooting

If tools do not appear, look for the starting - 8 tools diagnostic and restart the client.
If run fails, inspect errors, exit_status, and log.
If a validation category is unfamiliar, read pyxel://validation-patterns.

MCP Registry

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

License

MIT — see LICENSE.

Featured

CodeRabbit

AI writes the code. CodeRabbit catches the slop.

Try For Free →

inference shell

create and run specialised agents in minutes

build now →

MCP-ready Email Sending

Plug Mailtrap into your AI workflow and let it handle the email.

Connect Mailtrap MCP →

Make your agent a DeFi expert

Agent, run crypto. Access onchain data & trade routes via 1inch.

Install now →

Capacitor - Shared memory for your team’s coding agents.

Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.

Try For Free →

CodeScene MCP Server

Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.

Try For Free →

Give your AI the whole web as clean markdown

Integrate web data into your AI product. One API to scrape website & brand data.

Get API Key Now →

belt - the only tool your agent needs

belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...

one prompt install →

pyxel-mcp

An MCP server for observing programs built with Pyxel. It runs trusted local scripts headlessly and returns structured state, pixels, assets, audio, and frame differences.

The server deliberately reports facts rather than a universal quality score. The agent using it chooses the checks that matter for the game.

Install

With Claude Code:

claude mcp add pyxel -- uvx pyxel-mcp

For another MCP client, run uvx pyxel-mcp install or add:

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

Restart the client after changing its configuration. The server writes this diagnostic to stderr:

[pyxel-mcp] starting - 8 tools

Tools

Every script argument is a file path, not Python source.

Tool	Returns
`validate`	Syntax errors and recognizable Pyxel code patterns.
`run`	Headless frames, scheduled input, logs, and `state`, `screen_image`, `screen_grid`, or `video` snapshots.
`pyxel_info`	Installed versions, paths, examples, and resource URIs.
`read_palette`	Palette colors and image-bank indices in use.
`read_image`	Image-bank pixels and an optional PNG render.
`read_tilemap`	Tile coordinates, source bank, usage counts, bounds, and an optional render.
`read_audio`	A rendered sound or music WAV plus measurable audio data.
`diff_frames`	Pixel differences between two PNG files.

All tools declare input and output schemas. Every result includes ok and errors.

Example

Capture state and the screen when a condition first becomes true:

{
  "script": "/absolute/path/game.py",
  "frames": 600,
  "until": "score >= 1",
  "snapshots": [
    {"kind": "state", "frame": "end", "attrs": ["score", "player.x"]},
    {"kind": "screen_image", "frame": "end", "output": "/tmp/goal.png"}
  ]
}

Use absolute artifact paths. Read log even when ok is true, and inspect captured images directly when appearance matters.

Resources

pyxel://run-snapshots-schema — complete run.snapshots grammar.
pyxel://validation-patterns — categories reported by validate.
pyxel://palette/default — default palette table.
pyxel://examples/{name} — source for an example bundled with the installed Pyxel package; discover names with pyxel_info.

Full game-building guidance lives in the separate pyxel-skill project; this package contains only the MCP server.

Update

uvx caches packages. Force a refresh with:

uvx --refresh-package pyxel-mcp pyxel-mcp install

Troubleshooting

If tools do not appear, look for the starting - 8 tools diagnostic and restart the client.
If run fails, inspect errors, exit_status, and log.
If a validation category is unfamiliar, read pyxel://validation-patterns.

MCP Registry

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

License

MIT — see LICENSE.

Pyxel MCP

pyxel-mcp

Install

Tools

Example

Resources

Update

Troubleshooting

MCP Registry

License

Pyxel MCP

pyxel-mcp

Install

Tools

Example

Resources

Update

Troubleshooting

MCP Registry

License

Related Design & Creative MCP Servers

Related Design & Creative MCP Servers