MCP Mgba

What dmang-dev/mcp-mgba MCP server does

dmang-dev/mcp-mgba MCP server gives an MCP client control over a running mGBA instance. It supports both Game Boy Advance and Game Boy/Game Boy Color ROMs, with platform information reported through mgba_get_info. Agents can inspect emulator metadata, read memory, write values directly to mapped addresses, queue controller input, advance execution by exact frame counts, pause or resume emulation, reset the ROM, save PNG screenshots, and manage emulator save states.

The memory tools cover 8-bit, 16-bit, 32-bit, and contiguous byte-range operations. Save states can use mGBA-managed slots from 0 through 9 or explicit filesystem paths. This makes the server suitable for workflows such as examining game state, applying controlled memory changes, replaying input sequences, and restoring a known baseline after an experiment.

How it works

The project has two cooperating parts. The Lua script runs inside mGBA's scripting engine and opens a loopback TCP listener on port 8765. The Node.js MCP process communicates with that bridge using newline-delimited JSON, then exposes the emulator operations to the client over standard MCP stdio.

Start a session with mgba_ping to check connectivity, then call mgba_get_info to identify the loaded ROM and inspect which optional emulator methods are available. Features such as pause, reset, frame advancement, screenshots, and state files depend on the loaded mGBA build. The bridge reports those capabilities so clients can avoid calling unavailable methods.

Setup and configuration

Use mGBA 0.10 or newer with Lua scripting and Node.js 22 or newer. Install the server from npm with npx -y mcp-mgba or install it globally with npm install -g mcp-mgba.

In mGBA, load a ROM first, open Tools > Scripting, and load lua/bridge.lua from the repository. The MCP process then runs through stdio, while the Lua bridge accepts its emulator requests. Set MGBA_HOST to change the bridge host and MGBA_PORT to change the TCP port; the defaults are 127.0.0.1 and 8765.

Other clients that support standard MCP stdio can run the same server process. Restart a client after changing its server configuration so it re-enumerates the tools.

Tools and capabilities

• Check bridge liveness and retrieve ROM title, code, platform, frame count, and optional capabilities.
• Read or write individual 8-, 16-, and 32-bit values, or transfer up to 4096 bytes per range call.
• Queue presses for A, B, Select, Start, directional buttons, R, and L, with configurable hold and release durations.
• Advance the emulator by a specified number of frames without changing its pause state.
• Pause, resume, or reset the loaded ROM when the corresponding mGBA methods are available.
• Save and restore complete emulator state through slots or filesystem paths, and save the current display as a PNG.

Limitations and notes

Direct memory writes are destructive and bypass the cartridge bus model. On GB/GBC systems, they do not perform MBC bank switching or RAM-enable behavior, so ROM-region writes do not trigger mapper commands and SRAM writes bypass mapper gates. Use a prepared save state when cartridge SRAM needs to be initialized with normal mapper semantics.

Range operations are limited to 4096 bytes and must remain within mapped memory. Save states are tied to the ROM and a compatible mGBA version. Loading a mismatched state can fail or produce a corrupted run. Frame advancement is synchronous but scales with emulation time, so large jumps can take several seconds. The bridge must be loaded only once per mGBA process after a clean restart if a prior script reload leaves an old callback active.

For dmang-dev/mcp-mgba MCP server sessions, pause before a multi-read or write sequence when a consistent snapshot matters, and save state before risky mutations if rollback is required.