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

1. Open mGBA and load your Pokemon Fire Red ROM

2. Go to Tools > Scripting

3. File > Load Script → select lua/mgba_server.lua

4. 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

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