Gearboy: a Game Boy emulator with a debugger and an MCP server attached

What Gearboy is for, and who it is not for

Gearboy is an emulator first and a development tool second, but the second part is what distinguishes it. The README describes it as an accurate cross-platform Game Boy, Game Boy Color and Super Game Boy emulator in C++ with an embedded MCP server for AI debugging and development. The feature list backs that up: a just-in-time disassembler, CPU breakpoints, memory access breakpoints, code navigation by double-clicking JP, JR and CALL instructions, debug symbols, automatic labels, a memory editor, a trace logger, an IO inspector and a VRAM viewer with tiles, sprites, backgrounds and palettes.

That combination targets a narrow audience. If you are writing a Game Boy program, patching an existing ROM, or reverse-engineering cartridge behaviour, the debugger and the MCP server are the product. If you want to play Link's Awakening on a TV, Gearboy works, but you are paying for tooling you will not open. The standalone builds exist for Windows, Linux, BSD and macOS; the libretro core reaches a much longer platform list, including Raspberry Pi, PlayStation Vita, Nintendo 3DS and the Wii family, but that list is about playback, not about debugging.

The emulation core: mappers, link cable and the Super Game Boy path

The cartridge support list is unusually long for a hobby-scale emulator. The README names ROM, ROM + RAM, MBC1, MBC2, MBC3, MBC5, MBC6, MBC7, HuC-1, HuC-3, MMM01, Pocket Camera, TAMA5, MBC1M, Wisdom Tree, M161, Sachen MMC1, Sachen MMC2 and PKJD. MBC7 is the accelerometer mapper used by Kirby Tilt 'n' Tumble; Pocket Camera and TAMA5 are the odd peripherals that most emulators skip. Covering them suggests the author is chasing hardware accuracy rather than the common-case library.

Two other pieces of hardware behaviour are called out explicitly. Local two-instance link cable support exists on desktop platforms and in the libretro core, which means two running copies of Gearboy can be connected rather than requiring a single process to host two emulated consoles. The Super Game Boy is supported, and the README also lists LCD screen ghosting and LCD dot matrix effects, which are the display artefacts of the original panel rather than clean upscaled output. Battery-backed RAM saves are supported, and save states include preview and rewind.

The accuracy claim in the README is not measured there. No test suite results, no comparison against hardware captures and no per-game compatibility table appear in the material I have. Treat "accurate" as the project's own description until you have run the specific titles you care about.

Installing Gearboy on macOS, Linux and Windows

The release table is the practical part. On macOS the Homebrew path is a single cask command: brew install --cask drhelius/geardome/gearboy. The README notes that if Homebrew asks you to trust the third-party tap, you run brew trust --tap drhelius/geardome first. There are also direct ZIP downloads for Apple Silicon and Intel.

On Linux the project publishes an Ubuntu PPA under drhelius/ppa-geardome and a Fedora RPM under drhelius/rpm-geardome, plus direct ZIPs for Ubuntu 24.04 x64, Ubuntu 22.04 x64 and Ubuntu 24.04 ARM64. The README warns that libsdl3 may be required on Linux. On Windows there are x64 and ARM64 desktop ZIPs, and the notes mention that the Visual C++ Redistributable and the OpenGL Compatibility Pack may be needed.

For RetroArch users the core is documented at docs.libretro.com/library/gearboy, and development builds come from the GitHub Actions workflow. One feature worth knowing before you script anything: Gearboy loads a ROM from the command line when you pass the ROM path as an argument, and it also accepts drag and drop. Portable Mode is available on Windows, Linux and macOS, and can be triggered either with the --portable flag or by placing an empty file named portable.ini next to the binary, according to the README. That is the piece to use if you want a self-contained install on a USB stick with its own saves and configuration.

The MCP server is the unusual feature, and the least documented one

Most emulators with a debugger stop at a GUI. Gearboy embeds an MCP server, and the README says it exposes tools for execution control, memory inspection, hardware status, rewind and more, aimed at GitHub Copilot, Claude, Codex and similar clients. The download table lists an MCPB entry for all platforms and points at a separate MCP_README.md.

That is where the supplied material runs out. The main README does not document the transport, the port, the tool names or the argument schemas. It does not say whether the server runs inside the desktop application, as a separate binary, or both. Anyone evaluating Gearboy for agent-driven debugging should read MCP_README.md in the repository before assuming the integration works the way they expect, because the top-level README gives you the pitch and not the interface. This is the single biggest gap in the documentation as presented.

The design choice itself is coherent, though. Execution control, memory inspection and rewind are exactly the primitives an agent needs to step through a routine, read a value and back up when a hypothesis fails. Wrapping them in MCP rather than a bespoke protocol means any MCP-capable client can attach without a Gearboy-specific plugin. It also means the tool surface is only as good as its descriptions, which are not in the material I have.

Where Gearboy is the wrong tool

The libretro core and the standalone application are not the same product. The debugger, the memory editor, the trace logger and the VRAM viewer are listed as standalone features; the platform list for libretro is about running games on consoles, handhelds and embedded systems, where there is no window to open a disassembler in. If your plan is to load the Gearboy core in RetroArch and then debug a ROM, the README does not describe that workflow. You would be using the emulation half and leaving the development half behind.

There is a second limitation that is easy to miss. The README states plainly that Gearboy can run with or without a Boot ROM, and that loading one is optional. Boot ROM behaviour is not identical to running without it, so if your work depends on the boot sequence, you supply the Boot ROM yourself. The project does not ship one, and the README does not say where to obtain it. That is a legal and logistical step left to the user.

Finally, the licence. Gearboy is GPL-3.0. If you want to embed the emulator core in a closed-source product, the GPL is a problem, and nothing in the README suggests a dual-licensing arrangement. I am not giving legal advice; the point is that the licence is a design constraint you check before writing code against the emulator, not after.

How it compares with SameBoy and the RetroArch-native path

The obvious comparison is SameBoy, another cartridge-accurate Game Boy and Game Boy Color emulator written in C. The difference in approach is where the tooling lives. SameBoy's debugger is a separate build target with its own window and its own build flags, and it does not expose a network protocol for external tools. Gearboy puts the debugger in the same binary as the emulator and adds an MCP endpoint on top, so an editor agent can drive execution and read memory without a human clicking through a UI.

That matters if you are automating anything. It matters less if you are not, and SameBoy's documentation of its accuracy work is a different kind of artefact from Gearboy's feature list. Gearboy's README tells you which mappers it handles and which debugger views it has; it does not tell you how its timing compares. If timing accuracy on specific hardware edge cases is the deciding factor for you, neither README settles it and you would need to test both against the same ROM.

The other alternative is not an emulator at all: using RetroArch with any Game Boy core and a separate debugging tool. That avoids picking an emulator for its debugger, but it also means the memory view and the running emulator are separate processes with no shared state. Gearboy's argument is that one process holding both is worth more than a cleaner separation.

Release cadence, maintenance and what the licence means for forks

The release history is dense. 3.8.13, 3.8.14 and 3.8.15 all landed within roughly two weeks of each other in August and September 2026, and the repository's last push is shortly after the most recent tag. That pattern suggests active maintenance and small, frequent increments rather than long stabilization cycles. For a project you depend on, frequent point releases are usually good news, with one caveat: if you vendor a specific build, you should expect to rebase often, because the version you pin will age quickly.

Upgrade cost is low on the packaged paths. Homebrew upgrades the cask, the Ubuntu PPA and Fedora RPM track the project's own repositories, and the direct ZIPs are replaced per release. If you build from source, the README points at the GitHub Actions workflow for development builds, which is also where you would look to see what the build actually requires on each platform.

The GPL-3.0 licence is the constraint that outlives any version bump. A fork that links Gearboy's code and is distributed must be GPL-3.0 as well, and that applies to the emulator core whether you use the standalone build or the libretro core. Because the MCP server lives inside the same project, an agent integration built on it inherits the same terms. If your use is internal and you never distribute binaries, the practical effect is smaller, but the licence does not stop applying because the code is convenient.

Editorial conclusion

Adopt Gearboy if you are doing homebrew or ROM-hack work and want a debugger with breakpoints, a VRAM viewer and an MCP endpoint that an editor agent can drive; the desktop builds and the Homebrew cask make that a short install. Do not adopt it if you only want a RetroArch core, since the libretro build has no standalone debugger UI, and do not adopt it if your project cannot ship GPL-3.0 code. Before committing, verify one thing: that the MCP server starts and answers on your machine, because the README points at MCP_README.md rather than documenting the transport and tool schema inline.

Official sources

1. drhelius/Gearboy on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases