Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mGBA MCP Server dump sprite data from my Pokemon ROM after 60 frames"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server for mGBA emulator - enables programmatic control of Game Boy, Game Boy Color, and Game Boy Advance emulation.
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
Related MCP server: mcp-mgba
# Install with uv
uv pip install -e .
# Or with pip
pip install -e .Python 3.11+
mGBA (mgba-qt) installed and in PATH
xvfb-run (for headless operation on Linux)
Run a ROM for a specified number of frames and capture a screenshot.
{
"rom_path": "/path/to/game.gb",
"frames": 120,
"savestate_path": "/path/to/save.ss0"
}Read memory at specified addresses.
{
"rom_path": "/path/to/game.gb",
"addresses": [49664, 65471],
"frames": 60
}Read a contiguous range of memory.
{
"rom_path": "/path/to/game.gb",
"start_address": 49664,
"length": 256,
"frames": 60
}Dump OAM (Object Attribute Memory) sprite data.
{
"rom_path": "/path/to/game.gb",
"savestate_path": "/path/to/save.ss0",
"frames": 60
}Dump entity/actor data from WRAM.
{
"rom_path": "/path/to/game.gb",
"entity_base": 49664,
"entity_size": 24,
"entity_count": 10,
"frames": 60
}Execute a custom Lua script in the emulator.
{
"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
}Add to your Claude Code MCP settings:
{
"mcpServers": {
"mgba": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mgba-mcp", "mgba-mcp"]
}
}
}Once configured, Claude Code can use commands like:
Use mgba_dump_oam to check sprite palettes in rom/working/penta_dragon_dx_FIXED.gbUse mgba_read_range to dump entity data at 0xC200 for 256 bytesCommon 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)
MIT
Dump entity/actor data from WRAM - useful for analyzing game objects
Inputs: rom_path (required), entity_base, entity_size, entity_count, +2 more.
Dump OAM (Object Attribute Memory) sprite data - shows all 40 sprites with position, tile, flags, and palette
Inputs: rom_path (required), savestate_path, frames.
Read memory at specified addresses after running for some frames
Inputs: rom_path (required), addresses (required), savestate_path, frames.
Read a contiguous range of memory addresses
Inputs: rom_path (required), start_address (required), length (required), savestate_path, +1 more.
Run a GB/GBC/GBA ROM for a specified number of frames and capture a screenshot
Inputs: rom_path (required), frames, savestate_path.
Run a custom Lua script in the emulator. The script can use emu:read8(), emu:write8(), emu:screenshot(), callbacks:add(), etc.
Inputs: rom_path (required), script (required), savestate_path, timeout.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 6 tools
Each tool has a clearly distinct purpose with no overlap: dumping entity data, dumping sprite data, reading specific memory addresses, reading memory ranges, running the emulator, and running Lua scripts. The descriptions make it easy to differentiate between them, eliminating any ambiguity.
All tools follow a consistent 'mgba_verb_noun' pattern (e.g., mgba_dump_entities, mgba_read_memory, mgba_run_lua). This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming style.
With 6 tools, the set is well-scoped for an emulator debugging server, covering core operations like memory access, emulation control, and scripting. Each tool earns its place without feeling excessive or insufficient for the domain.
The tools provide strong coverage for emulator interaction, including memory inspection, execution control, and custom scripting. A minor gap exists in write operations (e.g., no mgba_write_memory), but agents can work around this using mgba_run_lua for modifications.
Drive your retro handheld console: find your games, launch, save, set volume, get cheat codes.
AI game maker: build, run, screenshot and play-test Godot and retro console games in a live project
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Disposable cloud Android emulators for coding agents: run an APK or PR build, tap, type, screenshot.
