mcp-mgba is a server based on the Model Context Protocol (MCP), designed to connect Claude (and other MCP-compatible clients) with the mGBA Game Boy Advance emulator.
Usage: This tool implements its functionality through a Lua script bridge. lua/bridge.lua runs inside mGBA's scripting engine and starts a TCP server on the local loopback address (port 8765). The MCP server written in Node.js (dist/index.js) communicates with the Lua bridge over TCP and exposes tools externally via stdio.
Main capabilities:
- Read and write GBA memory
- Inject button presses (supported buttons include A, B, Select, Start, Right, Left, Up, Down, R, L)
- Capture screenshots
- Single-step the emulator
Prerequisites:
- mGBA 0.10 or newer (Lua scripting support required)
- Node.js 22+ (for the MCP server)
Installation: Option A — Install from npm (recommended): after global installation, mcp-mgba is added to PATH. Option B — Use npx (no installation required): run on demand, suitable for trying it out. Option C — Clone the repository and develop: reference the absolute path to dist/index.js when registering, or use npm install -g . to link globally.
Setting up the mGBA bridge:
- Launch mGBA and load any GBA ROM.
- Open Tools > Scripting….
- Click File > Load script and select lua/bridge.lua in this repository. If a bind failed error appears, it means the socket from the previous instance is still occupied; you need to quit and restart mGBA.
Registering the MCP client:
- Claude Code (CLI): if using Option B and it is not globally installed, replace mcp-mgba with node /absolute/path/to/dist/index.js.
- Claude Desktop: edit claude_desktop_config.json and add the corresponding configuration, then restart Claude Desktop for it to take effect.
- Other MCP clients: this server uses the standard MCP protocol over stdio; run mcp-mgba (or node dist/index.js) and let any MCP client connect to its stdio.
More examples can be found in docs/RECIPES.md, which includes end-to-end cases such as RAM searching, snapshot-experiment-restore, and side-scrolling game automation.
Debugging and development:
- The Lua side (lua/bridge.lua and lua/json.lua) requires no build step; after editing, reload via mGBA's File > Load script.
- You can use MCP Inspector to interactively browse and call tools. If you have modified src/, build first (npm run build) or keep npm run dev running. You can override the bridge address via MGBA_HOST / MGBA_PORT (default 127.0.0.1:8765). Even if mGBA is not connected, tools/list also works; calling tools requires mGBA to be open and lua/bridge.lua to be loaded.
Use cases: Suitable for developers, researchers, or enthusiasts who want to automate control of the GBA emulator through AI models, such as automated testing, game AI experiments, memory analysis, etc.
Limitations: The environment must explicitly provide mGBA 0.10+ and Node.js 22+; the Lua bridge requires manually loading the script in mGBA; port occupation may cause conflicts and require restarting the emulator. Other specific limitations are not provided at this time.