PokeMCP - AI Plays Pokemon Fire Red

An MCP server that lets Claude play Pokemon Fire Red through the mGBA emulator. Built for YouTube content — Claude has its own personality, names its Pokemon, trash-talks its rival, and reacts to everything happening in the game.

How It Works

Claude <-> FastMCP Server (Python) <-> TCP Socket <-> Lua Script (inside mGBA)

Split gameplay model:

Claude handles: Battles, dialog, menus, naming (trainer/rival/Pokemon), team strategy
Human operator handles: Overworld navigation (walking to destinations)
Navigation is purely visual — Claude reads screenshots to understand the game world
RAM reading is used only for party Pokemon stats, battle data, badges, and money

Prerequisites

mGBA v0.10+ — mgba.io
Python 3.12+
uv — pip install uv
Pokemon Fire Red ROM — US v1.0 (game code: BPRE)

Setup

1. Install dependencies

uv sync

2. Load the Lua script in mGBA

Open mGBA and load your Pokemon Fire Red ROM
Go to Tools > Scripting
File > Load Script → select lua/mgba_server.lua
Console should show: MCP Server listening on 127.0.0.1:5555

3. Configure Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "pokemon-firered": {
      "command": "C:\\Users\\YOUR_USER\\AppData\\Roaming\\Python\\Python312\\Scripts\\uv.exe",
      "args": ["--directory", "C:/path/to/mGba MCP", "run", "mgba-mcp"]
    }
  }
}

Note: Use the full path to uv.exe — Claude Desktop may not have it in PATH. Find it with python -c "import shutil; print(shutil.which('uv'))".

4. Play!

Start a conversation with Claude. It will invent a personality, pick a trainer name, and start playing.

Available Tools

Tool	Description
`press_button`	Press a GBA button and get a screenshot
`press_buttons`	Press a sequence of buttons with timing
`get_screenshot`	See the current game screen
`get_game_state`	Read badges, money, party Pokemon, battle state from RAM
`get_party`	Detailed party info (stats, moves, IVs)
`get_battle_state`	Battle details (your/enemy Pokemon, HP, moves, PP)
`save_state`	Save emulator state (slots 1-9)
`load_state`	Load emulator state
`wait_frames`	Wait through animations/transitions
`hold_button`	Hold a button for extended walking/scrolling

What Claude Reads from RAM

Party Pokemon — Species, level, HP, moves with PP, stats, IVs, status conditions
Badges — Which gym badges have been earned
Money — Current funds (XOR-decrypted)
Battle state — Enemy Pokemon species, level, HP, moves

Navigation and dialog are handled visually through screenshots only.

Claude's Personality

Each session, Claude invents a unique persona:

Picks its own trainer name and rival name
Names every Pokemon with creative nicknames
Has strong opinions about Pokemon, moves, and characters
Gets emotionally invested — celebrates wins, mourns faints
Narrates its thought process for the audience
All commentary in Spanish for YouTube content

Project Structure

├── pyproject.toml
├── src/mgba_mcp/
│   ├── server.py        # FastMCP tools + personality instructions
│   ├── connection.py    # TCP client for mGBA communication
│   ├── game_state.py    # Pokemon Fire Red RAM parser
│   └── constants.py     # Memory addresses and lookup tables
├── lua/
│   └── mgba_server.lua  # Lua TCP server loaded into mGBA
└── data/
    ├── pokemon_species.json
    ├── pokemon_moves.json
    └── map_names.json

Tips for YouTube Recording

Save states are your friend — save before gyms, important battles, or risky catches
Let Claude fail — mistakes and reactions are entertaining content
Navigate for Claude — walk to destinations, let Claude handle the rest
Nudge when stuck — tell Claude "we're at the Pokemon Center" or "there's a trainer ahead"
The game is in English but Claude comments in Spanish — great for bilingual content

Important Notes

ROM must be US v1.0 (BPRE) for memory addresses to work
Load the Lua script in mGBA before starting Claude Desktop
mGBA must stay open while playing
The Lua script auto-detects the ROM and warns if it doesn't match

License

MIT

PokeMCP