Skip to main content
Glama
Canadadry

mcp-mgba

by Canadadry
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Local

mcp-mgba

A headless GBA debugger MCP server: it lets an LLM (or any MCP client) load a Game Boy Advance ROM, step it instruction-by-instruction, read/write memory, and manage breakpoints/watchpoints/registers — all with zero GUI toolkit dependency (no X server, no Qt, no SDL window). Under the hood it's built on mGBA's core emulation library (libmgba), built headless.

Prerequisites

  • cmake, a C compiler (gcc/clang), and make — for building the native shim.

  • Node.js >=18 and npm.

Related MCP server: mcp-mgba

Setup

git submodule update --init --recursive   # first time only
native/build.sh                            # build the native shim
npm install
npm run build                              # tsc -> dist/

Running

npm start        # runs dist/index.js over stdio
# or, for local development without a build step:
npm run dev       # runs src/index.ts directly via tsx

Point any MCP client at the built server to drive it interactively, e.g.:

npx @modelcontextprotocol/inspector node dist/index.js

By default the server locates its native shim next to itself (native/build/<platform>/ in a checkout, or prebuilt/<platform>/ in a published install). Set MCBAMGBA_SHIM_PATH to point it at a shim built elsewhere instead.

Tools

Tool

Description

load_rom

Loads a GBA ROM from an absolute path, replacing any ROM already loaded, and resets to its entry point. Required before any other tool.

reset

Resets the currently loaded ROM back to its entry point.

step

Executes a single CPU instruction.

run_frames

Advances execution by count whole video frames — faster than single-instruction stepping when that granularity isn't needed.

read_memory

Reads length bytes of GBA-mapped memory (IWRAM/EWRAM/ROM/palette/OAM/etc.) starting at address, returned as a hex string.

write_memory

Writes a hex-encoded byte string into GBA-mapped memory starting at address — patch state, force a flag, unlock progress.

press_button

Holds one or more of the GBA's 10 buttons (A, B, SELECT, START, RIGHT, LEFT, UP, DOWN, R, L) down for frames whole video frames, then releases them.

screenshot

Captures the current 240x160 frame as a PNG image.

save_state

Snapshots the current point in execution as an opaque, base64-encoded blob (never interpreted by the server) that load_state can return to later without replaying input.

load_state

Restores emulator state from a blob previously returned by save_state, for a core loaded from the same ROM.

set_breakpoint

Sets a hardware breakpoint at address. Fires just before the instruction at that address executes.

clear_breakpoint

Removes the breakpoint with the given id.

list_breakpoints

Lists every breakpoint currently set.

set_watchpoint

Sets a watchpoint at address for a given access kind (write, read, rw, change, write_change).

clear_watchpoint

Removes the watchpoint with the given id.

list_watchpoints

Lists every watchpoint currently set.

get_registers

Reads the full CPU register set (r0-r15, cpsr, ...) at the current point in execution.

set_register

Writes a single register by name (e.g. r0, pc, sp, lr, cpsr), to mutate CPU state and test a hypothesis.

run_until_breakpoint

Runs forward (single-stepping internally, one blocking call) until a breakpoint or watchpoint fires, or a safety max_instructions cap is reached. The response's stop_reason ("breakpoint" / "watchpoint" / "cap") unambiguously distinguishes a real hit from a timeout, alongside the id/address that fired and the current register set.

disassemble

Decodes count ARM/THUMB instructions starting at address into mnemonic + operand strings, using the CPU's current execution mode for the whole range.

Every tool other than load_rom fails with a structured [NO_ROM_LOADED] error if called before a ROM is loaded. clear_breakpoint, clear_watchpoint, and set_register fail with a structured [NOT_FOUND] error if given an id/register name that doesn't exist.

The server is fully synchronous/pull-based — every tool call blocks and returns a definitive result — and supports a single loaded ROM/session at a time.

License

MPL-2.0 — see LICENSE. Built on mGBA's libmgba (also MPL-2.0), vendored as a git submodule and statically linked into the compiled native shim this package distributes. See NOTICE for the exact vendored tag/commit.

This server cannot be installed

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • mcp-mgba

    dmang-dev
    A
    license
    A
    quality
    B
    maintenance
    MCP server for the mGBA Game Boy Advance emulator. Read and write GBA memory, inject button presses, take screenshots, save/load state, and step the emulator through a Lua bridge.
    18
    11
    2
    MIT

  • GDB Lite MCP

    Mort2000
    A
    license
    B
    quality
    D
    maintenance
    A lightweight MCP server that enables LLM agents to interact with GDB for debugging native programs, supporting spawning sessions, executing commands, interrupting hangs, and closing sessions.
    4
    8
    MIT

  • gdb-mcp

    datobena
    A
    license
    B
    quality
    C
    maintenance
    MCP server that wraps gdb to enable LLMs to drive live debugging sessions, including starting sessions on binaries, attaching to processes, and running commands.
    7
    3
    MIT