# mgba-mcp
MCP (Model Context Protocol) server for mGBA emulator - enables programmatic control of Game Boy, Game Boy Color, and Game Boy Advance emulation.
## Features
- **Headless execution** - Runs via xvfb for automated testing
- **Screenshot capture** - Get PNG screenshots at any frame
- **Memory reading** - Read individual addresses or memory ranges
- **OAM dumping** - Dump all 40 sprite entries with position, tile, flags, and palette
- **Entity dumping** - Read game entity/actor data from WRAM
- **Custom Lua scripts** - Execute arbitrary Lua code in the emulator
- **Savestate support** - Load savestates for reproducible testing
## Installation
```bash
# Install with uv
uv pip install -e .
# Or with pip
pip install -e .
```
### Requirements
- Python 3.11+
- mGBA (mgba-qt) installed and in PATH
- xvfb-run (for headless operation on Linux)
## MCP Tools
### mgba_run
Run a ROM for a specified number of frames and capture a screenshot.
```json
{
"rom_path": "/path/to/game.gb",
"frames": 120,
"savestate_path": "/path/to/save.ss0"
}
```
### mgba_read_memory
Read memory at specified addresses.
```json
{
"rom_path": "/path/to/game.gb",
"addresses": [49664, 65471],
"frames": 60
}
```
### mgba_read_range
Read a contiguous range of memory.
```json
{
"rom_path": "/path/to/game.gb",
"start_address": 49664,
"length": 256,
"frames": 60
}
```
### mgba_dump_oam
Dump OAM (Object Attribute Memory) sprite data.
```json
{
"rom_path": "/path/to/game.gb",
"savestate_path": "/path/to/save.ss0",
"frames": 60
}
```
### mgba_dump_entities
Dump entity/actor data from WRAM.
```json
{
"rom_path": "/path/to/game.gb",
"entity_base": 49664,
"entity_size": 24,
"entity_count": 10,
"frames": 60
}
```
### mgba_run_lua
Execute a custom Lua script in the emulator.
```json
{
"rom_path": "/path/to/game.gb",
"script": "callbacks:add('frame', function() if emu:currentFrame() > 60 then emu:screenshot('screenshot.png'); emu:quit() end end)",
"timeout": 30
}
```
## Claude Code Integration
Add to your Claude Code MCP settings:
```json
{
"mcpServers": {
"mgba": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mgba-mcp", "mgba-mcp"]
}
}
}
```
## Usage Example
Once configured, Claude Code can use commands like:
```
Use mgba_dump_oam to check sprite palettes in rom/working/penta_dragon_dx_FIXED.gb
```
```
Use mgba_read_range to dump entity data at 0xC200 for 256 bytes
```
## Memory Addresses (Game Boy)
Common memory regions:
- `0x8000-0x9FFF` - VRAM (tile data)
- `0xC000-0xDFFF` - WRAM (work RAM)
- `0xFE00-0xFE9F` - OAM (sprite attributes)
- `0xFF00-0xFF7F` - I/O registers
- `0xFF80-0xFFFE` - HRAM (high RAM)
## License
MIT
