dmang-dev/mcp-mgba

An MCP server that exposes the mGBA Game Boy Advance emulator to any MCP-compatible client (Claude Desktop, Claude Code, etc.).
Lets your model **read and write GBA memory, inject button presses, take screenshots, and step the emulator** — all through a clean tool interface.
*Claude driving an in-development homebrew side-scroller through mgba_press_buttons — Start to begin, A to confirm New Game, then Right to walk and A to jump. Each frame is captured via mgba_screenshot.*
How it works
Two pieces:
- **lua/bridge.lua** — runs *inside* mGBA's scripting engine, opens a loopback TCP server on port 8765
- **dist/index.js** — Node.js MCP server, talks to the Lua bridge over TCP, exposes tools over stdio
Requirements
- mGBA **0.10 or newer** (with Lua scripting)
- **Node.js 22+** (for the MCP server)
Install
Option A — install from npm (recommended)
Puts mcp-mgba on your PATH. Verify with mcp-mgba --help (it'll print a startup line and wait for stdio — Ctrl+C to exit).
Option B — npx (no install)
Run on demand. Good for trying it out without committing to a global install.
Option C — clone and develop
Then reference the absolute path to dist/index.js when registering, or npm install -g . to symlink the bin globally.
Set up the mGBA bridge
1. Launch mGBA and load any GBA ROM.
2. Open **Tools > Scripting…**
3. Click **File > Load script** and select lua/bridge.lua from this repo.
You should see in the scripting console:
If you see a bind failed error, the previous instance's socket is still held — quit and relaunch mGBA.
Register with your MCP client
Claude Code (CLI)
(if you used Option B without global install, replace mcp-mgba with node /absolute/path/to/dist/index.js)
Verify:
Claude Desktop
Edit claude_desktop_config.json:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
Add (assuming Option A — globally installed):
Or with explicit Node + path (Option B):
Restart Claude Desktop after editing.
Other MCP clients
The server speaks standard MCP over stdio. Run mcp-mgba (or node dist/index.js) and connect any MCP client to its stdio.
Configuration
| Env var | Default | Purpose |
|-------------|---------------|------------------------|
| MGBA_HOST | 127.0.0.1 | Bridge host to dial |
| MGBA_PORT | 8765 | Bridge port to dial |
Tools
| Tool | Description |
|------|-------------|
| mgba_ping | Verify bridge connectivity (returns pong) |
| mgba_get_info | Game title, code, frame count |
| mgba_read8 / mgba_read16 / mgba_read32 | Read memory at an address |
| mgba_write8 / mgba_write16 / mgba_write32 | Write to RAM |
| mgba_read_range | Read up to 4096 bytes as a byte array |
| mgba_write_range | Write up to 4096 bytes from a byte array |
| mgba_press_buttons | Queue a button press (FIFO; consecutive calls produce distinct events) |
| mgba_advance_frames | Step the emulator N frames |
| mgba_pause / mgba_unpause | Pause / resume emulation |
| mgba_reset | Reset the loaded ROM |
| mgba_screenshot | Save a PNG of the current display |
| mgba_save_state / mgba_load_state | Save/load emulator state to a slot or path |
See docs/RECIPES.md for end-to-end examples (RAM hunting, snapshot-experiment-restore, side-scroller automation, etc.).