MGBA

Provides programmatic control of mGBA emulation for screenshots, memory access, OAM/entity dumps, and savestates.

typescript

0

GitHub Stars

typescript

Language

6 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "struktured-labs-mgba-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/mgba-mcp",
        "mgba-mcp"
      ]
    }
  }
}

You can control mGBA emulation programmatically with this MCP server. It lets you run ROMs headlessly, capture screenshots, read memory, dump graphics and entities, run Lua scripts, and load savestates — all through a simple MCP interface that you can call from your tooling. This makes automated testing, debugging, and data collection for Game Boy titles straightforward and reproducible.

How to use

You interact with the MCP server from a client that speaks the MCP protocol. You can run a ROM for a set number of frames and capture a screenshot, read specific memory addresses or ranges, dump sprite and WRAM data, and execute custom Lua code inside the emulator. When you want repeatable tests, load savestates and drive exact frame counts to reproduce outcomes.

How to install

Prerequisites you need before installing the MCP server:

Python 3.11+
mgba-qt in PATH
xvfb-run

Installation steps

# Install with uv
uv pip install -e .

# Or with pip
pip install -e .

Available tools

mgba_run

Run a ROM for a specified number of frames and capture a screenshot to verify visuals and timing.

mgba_read_memory

Read one or more memory addresses from the running ROM to inspect game state.

mgba_read_range

Read a contiguous block of memory to quickly inspect larger regions.

mgba_dump_oam

Dump Object Attribute Memory data to inspect sprite properties, positions, and palettes.

mgba_dump_entities

Dump WRAM-based entity/actor data to analyze in-game objects and AI state.

mgba_run_lua

Execute a custom Lua script inside the emulator to automate tests or data collection.