Game Boy MCP Player

An MCP (Model Context Protocol) server that lets an AI agent play any Game Boy game through a small, token-efficient set of tools, and records benchmark metrics while it plays.

Pokémon Red/Blue/Yellow get a built-in game profile that reads party, battle, map and dialogue straight from memory, so the agent plays mostly from text instead of screenshots, and gets high-level helpers (pathfinding, whole-battle turns, conversations, shops, party management). Any other ROM works with the generic profile (button scripts, screenshots, save states, raw memory).

Status

• Played from power-on to the Boulder Badge by a scripted reference agent using only the public tools, cleanly on four different RNG seeds (examples/reference_run.py, about 35 s of real time and 1,400 tool calls per run).

• A second scripted run (examples/extended_run.py) continues from the Boulder Badge through Mt. Moon to Cerulean City and Misty, covering caves, trainers, in-battle items, field moves and the world graph.

• 57 automated tests, including a replay of the game's opening, an MCP client round-trip and the benchmark harness's stream parsers.

• A public benchmark: agent CLIs (Claude Code, Codex) play from power-on toward the Champion with the same prompt and budgets; see RESULTS.md and BENCHMARKING.md.

• Save states are not included in the repository (they contain emulator memory derived from the ROM). Create your own with save_state("after-brock") at the post-Brock point and reload it with load_state("after-brock").

Related MCP server: PokeMCP

Why this version is fast and cheap

Quick start

No ROM is included and none will be accepted into the repository. Use a cartridge dump you legally own; the .gitignore excludes *.gb, *.gbc, *.ram, saves/, screenshots/ and metrics/.

python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python test_emulator.py path/to/game.gb                  # smoke test (add --play-intro for Pokémon)
python -m pytest tests                                    # full suite (needs a Pokémon Red/Blue ROM in the folder)
python examples/reference_run.py path/to/pokemon-red.gb   # scripted agent: power-on to Brock

Then point your MCP client at server.py (see QUICKSTART.md):

{
  "mcpServers": {
    "gameboy": {
      "command": "/ABS/PATH/pokemon-ai-player/venv/bin/python",
      "args": ["/ABS/PATH/pokemon-ai-player/server.py", "--rom", "/ABS/PATH/game.gb", "--ai-model", "claude-fable-5-1"]
    }
  }
}

Tools

Every action returns the same compact block: a status line (position, party, money, badges), EVENT: lines for milestones, the decoded screen text (or the map after a walk), a hint: line whenever the game is waiting for an answer, and a PNG only when the screen changed. The server also sends a short agent guide as MCP instructions; AGENT_GUIDE.md is the long version.

Server options

python3 server.py --rom GAME.gb [--ai-model NAME] [--profile auto|generic|pokemon-gen1|pyboy-wrapper]
                  [--scale 1-4] [--resume] [--autosave-every N] [--no-fast-text]
                  [--no-screenshot-files] [--allow-memory-write] [--charmap map.json] [--data-dir DIR]
                  [--session-id ID] [--max-tool-calls N] [--max-real-seconds S] [--finalize-on-exit]
                  [--log-file FILE]

• --resume continues from saves/<rom>/autosave.state.

• --no-fast-text disables the Pokémon quality-of-life tweak (text speed FAST, battle animations OFF, battle style SET; identical to the in-game OPTION menu).

• --charmap lets the generic profile decode on-screen text for other games: a JSON object mapping tile IDs (hex strings) to characters.

• --data-dir puts screenshots/, saves/ and metrics/ somewhere other than next to server.py.

• --session-id continues one metrics session across launches (with --resume); --max-tool-calls / --max-real-seconds end a benchmark run cleanly (BUDGET EXHAUSTED); --finalize-on-exit writes the final report when the server stops.

Layout

server.py               MCP entry point (FastMCP), tool definitions, agent guide
emulator.py             PyBoy wrapper: scripts, walking, pathfinding executor, screenshots, save states, memory
metrics.py              generic benchmark tracker
games/__init__.py       profile registry (matched on the ROM header title)
games/base.py           GameProfile interface + generic tilemap text decoder
games/pokemon_gen1.py   Red/Blue/Yellow profile: state, maps, routing, battle/talk/shop/manage helpers, milestones
games/gen1_data.py      verified addresses, charmap, species/move/item/map tables
games/pyboy_wrapped.py  Tetris / Super Mario Land / Kirby / Pinball via PyBoy wrappers
examples/reference_run.py  scripted agent that plays to Brock with the public tools (also a regression run)
examples/extended_run.py   scripted agent: Boulder Badge -> Mt. Moon -> Cerulean -> Misty
examples/_agentlib.py      helpers shared by the scripted agents
bench/                  benchmark harness: run.py (drives Claude Code / Codex headless), report.py (RESULTS.md)
results/                one JSON per published benchmark run; RESULTS.md is generated from them
tests/                  pytest suite: parsers, ROM-driven gameplay, opening replay, MCP round-trip, harness

Docs: QUICKSTART.md, AGENT_GUIDE.md, BENCHMARKING.md, CLAUDE.md (maintainer notes and verified ROM facts).

Adding a game profile

Subclass games.base.GameProfile, implement status_line(), state(), snapshot() and milestones(), and optionally position() (enables smart walking), screen_text(), find_path(), battle_action(), talk(), shop() and manage(). Register a cartridge-title regex in games/__init__.py.

Legal

No ROMs are included. Use only games you own.

License

MIT, see LICENSE. Pokémon and Game Boy are trademarks of Nintendo; no ROM is included.