Pyxel MCP

io.github.kitao由 GitHub 帳號 kitao 發布v1.4.0更新於 Nov 12, 2026

MCP server for Pyxel, a retro game engine for Python

已驗證STDIO僅桌面開發者工具媒體與設計

概覽

AI 產生的概覽

本機 MCP 伺服器,可無介面執行 Pyxel 復古遊戲腳本,注入依畫格排程的輸入,並回傳截圖、狀態、素材、音訊與畫格差異。

可以做什麼
  • 在不執行的情況下檢查 Pyxel 腳本的語法與可辨識的程式碼模式
  • 無介面執行腳本,依畫格排程按鍵、軸與滑鼠輸入,設定畫格上限與停止條件,並擷取狀態、畫面、格線或影片快照
  • 查看已安裝版本、型別存根路徑、內建範例與資源 URI
  • 讀取調色盤顏色、影像庫像素與圖磚地圖資料,可選擇輸出為 PNG
  • 將某個音效或音樂槽輸出為 WAV 並回傳可量測的音訊資料
  • 逐像素比較兩張 PNG 畫格,回報變化區域與比例
適用情境
適合在助理撰寫或修改 Pyxel 遊戲後,需要實際試玩、觀察與量測而非憑猜測判斷時使用:驗證輸入是否產生預期畫面、在遊戲條件成立時擷取該時刻,或檢查像素美術、圖磚地圖與音訊。
執行需求
本機 stdio 程序,通常以 uvx 啟動。需要 Python 3.11 以上版本,以及作為相依套件安裝的 Pyxel 3.0.1 以上版本。腳本參數必須是絕對檔案路徑;未宣告帳號、API 金鑰或環境變數。
安裝前請注意
腳本工具會在子程序中執行本機 Python,且明確不是沙箱,因此只應執行可信的腳本。執行會把 PNG、WAV 與影片產物寫入指定路徑,內嵌畫格則寫入系統暫存目錄。pyxel.run() 之後的陳述式不會執行,而抑制內部停止訊號的腳本可能執行執行後的程式碼。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Pyxel MCP,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only,透過 STDIO。 STDIO 服務會啟動本機處理程序,因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

pyxel-mcp

Let AI agents play, watch, and measure Pyxel games. pyxel-mcp is an MCP server that runs a Pyxel script headlessly, feeds it scheduled input, stops when a condition holds, and hands back the facts: screenshots, pixel grids, game state, assets, audio, and frame diffs.

[PyPI] [Python] [Tests] [License] [MCP Registry]

[Pyxel's bundled platformer example driven headlessly with right held and three scheduled jumps] [Frame 80 of the same run at scale 3, returned inline as image content]

Both images come from one run call against Pyxel's bundled 10_platformer.py: 150 frames, right held from frame 0, jumps scheduled at frames 25, 70, and 110, a video snapshot, and an inline screen_image snapshot.

Why

An agent can write a Pyxel game in seconds, but it cannot open a window, press the arrow keys, or look at the screen. Editor-bound engines solve this with MCP servers that live inside the editor. Pyxel has no editor process to attach to, so pyxel-mcp drives the game itself:

  • Headless execution. Every call runs the script in a fresh subprocess with SDL dummy drivers and a frame budget. Set random_seed to seed Python's random module and Pyxel's random generator. Other randomness, timing, and external state can still affect the frames.
  • Input as data. Buttons, axes, and mouse position are scheduled per frame, so a playtest is a JSON document the agent can rerun and extend.
  • Stop on the event, not the clock. until="score >= 1" ends the run at the first frame where a game attribute holds, and "frame": "end" snapshots capture that moment.
  • Facts, not scores. Tools report pixels, values, and measurements. Deciding whether the game is good stays with the agent and the person asking for it.
  • See the frame in the result. inline: true returns a PNG as MCP image content, so the model looks at the screen without a second file read.

Install

Register the stdio server with your client:

bash
claude mcp add --scope user pyxel -- uvx pyxel-mcp
bash
codex mcp add pyxel -- uvx pyxel-mcp
bash
gemini mcp add pyxel uvx pyxel-mcp

For Cursor (~/.cursor/mcp.json), a project-scoped Claude Code .mcp.json, or any other client that reads the common JSON format, add:

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

VS Code uses .vscode/mcp.json with a top-level servers key and "type": "stdio"; Codex CLI can also be configured in ~/.codex/config.toml as [mcp_servers.pyxel]. Run uvx pyxel-mcp install to print every variant.

Claude Code users can instead install the pyxel-skill plugin, which registers this server together with the skill that teaches agents how to use it:

bash
claude plugin marketplace add kitao/pyxel-skill && claude plugin install pyxel@pyxel-skill

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

text
[pyxel-mcp] starting - 8 tools

Python 3.11+ is required, and Pyxel >= 3.0.1 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.

How an agent uses it

mermaid
flowchart LR    W["Write or edit<br>game.py"] --> V["validate"]    V --> R["run<br>inputs · until · snapshots"]    R --> O{"Inspect facts<br>state · pixels · log"}    O -- "defect" --> W    O -- "looks right" --> A["read_image · read_tilemap<br>read_audio · diff_frames"]    A --> D["Report evidence"]

The loop is deliberately small. The separate pyxel-skill project teaches agents when to use each tool and what counts as enough evidence; this package only supplies the observations.

Tools

Every script argument is a file path, not Python source. Relative asset paths inside the script resolve from the script's directory, as when running python game.py from that directory.

ToolReturns
validateSyntax errors and recognizable Pyxel code patterns, without executing.
runHeadless frames, scheduled input, logs, and state, screen_image, screen_grid, or video snapshots.
pyxel_infoInstalled versions, Pyxel and Cube type stub paths, bundled examples, and resource URIs.
read_palettePalette colors and image-bank indices in use.
read_imageImage-bank pixels and an optional PNG render.
read_tilemapTile coordinates, source bank, usage counts, bounds, and an optional render.
read_audioA rendered sound or music WAV plus measurable audio data.
diff_framesPixel differences between two PNG files.

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

Script tools observe the first pyxel.run() call while its enclosing resources remain active. run drives the callbacks there; the asset readers inspect the pre-loop state. pyxel.quit() ends a run normally and preserves completed frames. Statements after pyxel.run() are not executed. Enclosing cleanup runs after observation, and cleanup failures are reported with phase: "script_exit". Stopping uses internal BaseException signals. Scripts or context-manager cleanup that suppress these signals are unsupported and may execute post-run code.

Captured PNGs can travel inside the result: set inline: true on a screen_image snapshot, or inline=true on read_image and read_tilemap, and the PNG is returned as MCP image content next to the structured data. A single inline frame may omit its output path; the file is then written under the system temp directory and its path is still reported, so diff_frames and later comparisons keep working. At most 12 images are embedded per call.

Pyxel Cube

Pyxel 3 adds software-rendered 3D through pyxel.cube. Use the same run tool, scheduled inputs, and screen snapshots to observe Cube programs. pyxel_info includes Cube examples such as cube/c01_hello_cube; pass an example's path to run so its bundled assets resolve correctly. Read its source through pyxel://examples/cube/c01_hello_cube.

stubs_path and cube_stubs_path point to the API type stubs installed with Pyxel. The Pyxel API reference and Cube API reference provide full descriptions. State snapshots can inspect explicit numeric paths such as scene.camera.transform.pos.x; whole Cube objects are returned as text representations. The asset readers continue to inspect image banks, tilemaps, and audio; they do not export a Cube scene or mesh.

When updating older projects, Pyxel 3 no longer accepts the old MML syntax or pre-2.0 resource files. See the current MML commands.

Example

Hold right, jump at frame 25, stop as soon as the score changes, and look at that frame:

json
{  "script": "/absolute/path/game.py",  "frames": 600,  "random_seed": 7,  "inputs": [    {"frame": 0, "buttons": ["KEY_RIGHT"]},    {"frame": 25, "buttons": ["KEY_RIGHT", "KEY_SPACE"]},    {"frame": 26, "buttons": ["KEY_RIGHT"]}  ],  "until": "score >= 1",  "snapshots": [    {"kind": "state", "frame": "end", "attrs": ["score", "player.x"]},    {"kind": "screen_image", "frame": "end", "scale": 3, "inline": true}  ]}

The result reports until_met, the reached frame_count, the requested state values, the PNG path, and the PNG itself as image content. Artifact paths you choose must be absolute. Read log even when ok is true, and inspect captured images directly when appearance matters.

Resources

  • pyxel://run-snapshots-schema — complete run.snapshots grammar, including "end", ranges, and inline.
  • pyxel://validation-patterns — categories reported by validate.
  • pyxel://palette/default — default palette table.
  • pyxel://examples/{name} — source for a top-level example bundled with the installed Pyxel package.
  • pyxel://examples/cube/{name} — source for a bundled Pyxel Cube example.

Discover examples with pyxel_info. Append its returned name to pyxel://examples/ to read the source, or pass its path to run.

Update

uvx caches packages. Force a refresh with:

bash
uvx --refresh-package pyxel-mcp --refresh-package pyxel 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 script cannot find an asset, check the path relative to the script file, not to the client's working directory.
  • If a validation category is unfamiliar, read pyxel://validation-patterns.

Related

  • Pyxel — the retro game engine this server observes.
  • pyxel-skill — the Agent Skill that turns these tools into a build-and-verify workflow.
  • CHANGELOG.md — what changed in each release.

MCP Registry

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

License

MIT — see LICENSE.

來源:README.md,提交 9fe0e04

工具

8

run

Run Pyxel script headlessly

Run a Pyxel script headlessly for a frame budget or until a condition holds, with scheduled input and state, screen, or video capture. screen_image snapshots with inline=true also return the PNG as image content, and a single inline frame may omit its output path.

輸入參數untilframes必填inputsscript必填timeoutsnapshotsrandom_seedstall_window_frames

validate

Validate Pyxel script

Check Python syntax and report recognizable Pyxel code patterns.

輸入參數script必填

pyxel_info

Pyxel environment info

Report installed versions, Pyxel and Cube type stub paths, examples, and resource URIs.

無需輸入參數。

read_palette

Read Pyxel palette

Read the active Pyxel palette and the palette indices used by image banks.

輸入參數script必填

read_image

Read image bank region

Read palette-index pixels from a Pyxel image-bank region and optionally render it to PNG; inline=true returns the render as image content and makes render_path optional.

輸入參數hwxyimage必填inlinescript必填render_path

read_tilemap

Read tilemap

Read Pyxel tile coordinates, usage, bounds, source bank, and optional rendered output; inline=true returns the render as image content and makes render_path optional.

輸入參數inlinescript必填tilemap必填render_path

read_audio

Render audio to WAV

Render one Pyxel sound or music slot to WAV and return measurable audio data. Notes describe tracker fields, not an MML or PCM transcription.

輸入參數script必填target必填output_path必填

diff_frames

Diff two frames

Compare two PNG frames pixel by pixel and return their changed region and ratio.

輸入參數frame_a必填frame_b必填

版本歷史

4
  1. v1.4.0最新Nov 12, 2026
  2. v1.3.2Oct 24, 2026
  3. v1.3.1Sep 22, 2026
  4. v1.3.0Sep 16, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分
  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭,或保持端點能夠回應探測,以便判定其認證方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分