Gearboy: A Cross-Platform Game Boy Emulator with MCP Server and Full Debugger

What Gearboy Is and Who It Is For

Gearboy is a C++ Game Boy emulator targeting accuracy over speed. The README describes it as accurate and cross-platform, supporting the original Game Boy, Game Boy Color, and Super Game Boy hardware modes. It is not a reimplementation of a commercial emulator; it is an independent open-source project.

The primary users are three groups: retro gaming enthusiasts who want to play Game Boy ROMs on a desktop operating system with save states and rewind; developers who need to debug Game Boy software and want a disassembler, breakpoints, and memory inspection built into the emulator; and developers who want to drive emulator state from an AI assistant, which the MCP server supports. The Super Game Boy support and link cable support for two desktop instances add niche use cases beyond basic emulation.

Gearboy version 3.8.16 was released on 2026-09-28, the same day as this review, indicating active development. The prior releases, 3.8.15 on 2026-09-01 and 3.8.14 on 2026-08-26, show a steady release cadence.

Getting Gearboy: Platform-by-Platform Installation

Gearboy offers pre-built binaries for each major platform in the GitHub releases.

On macOS, the simplest path is Homebrew:

brew install --cask drhelius/geardome/gearboy

If Homebrew prompts about trusting the third-party tap, the README says to run:

brew trust --tap drhelius/geardome

On Linux, Ubuntu users can use the PPA at drhelius/ppa-geardome, and Fedora users can use the RPM repository at drhelius/rpm-geardome. Direct ZIP downloads are available for Ubuntu 24.04 and 26.04 on both x64 and ARM64.

On Windows, the release includes ZIP archives for x64 and ARM64. The README notes that Windows users may need the Visual C++ Redistributable and the OpenGL Compatibility Pack from the Microsoft Store.

For RetroArch, the libretro core is documented at the Libretro core documentation page. Gearboy also runs as a RetroArch core on platforms including Raspberry Pi, Android, iOS, Nintendo Switch, PlayStation Vita, and WebAssembly.

The README also lists a Linux Snap package and a Flatpak. Portable Mode is available on Windows, Linux, and macOS by starting the application with the --portable flag, or by placing a portable.ini file in the same directory as the binary.

Hardware Accuracy and Cartridge Support

Gearboy supports an extensive list of cartridge types. The README lists: ROM only, ROM plus RAM, MBC1, MBC2, MBC3, MBC5, MBC6, MBC7, HuC-1, HuC-3, MMM01, Pocket Camera, TAMA5, MBC1M, Wisdom Tree, M161, and several unlicensed mapper types including Sachen MMC1, Sachen MMC2, PKJD, Bung/EMS, Li Cheng, NT newer, GGB81, Hitek, VF001, VF001 (SL), Sintax, NT old 1, and NT old 2. This breadth of mapper support means that licensed commercial games and most unlicensed cartridges should load.

The emulator includes features that contribute to accuracy and authenticity: LCD screen ghosting to replicate the original Game Boy display behavior, LCD dot matrix effects, battery-powered RAM save support, and Bootrom (BIOS) support. Game Genie and GameShark cheat codes are supported.

For audio fidelity, Gearboy includes a VGM recorder that can capture audio output. The emulator supports local two-instance link cable emulation on desktop platforms and the libretro core, which is needed for some multiplayer Game Boy Color games.

Run-ahead support is available to reduce perceived input latency by pre-computing frames. This is a feature found in accuracy-focused emulators and is more commonly seen in libretro cores than in standalone emulators.

The Built-in Debugger

The debugger in Gearboy is one of its distinguishing features relative to simpler Game Boy emulators. The README lists the debugger's capabilities: a just-in-time disassembler, CPU breakpoints, memory access breakpoints, code navigation with goto-address support, JP and JR and CALL instruction following by double-clicking, debug symbol support, automatic label generation, a memory editor, a trace logger, an IO inspector, and a VRAM viewer showing tiles, sprites, backgrounds, and palettes.

This set of tools is more comprehensive than most emulator debuggers and is useful for Game Boy homebrew developers who need to diagnose issues in ROM code. The disassembler operates just-in-time rather than pre-analyzing the entire ROM, which means it handles self-modifying code correctly.

The debug symbol support means that developers who build their Game Boy code with symbol files can have the debugger display named labels instead of raw addresses. Automatic label generation fills in names for standard hardware registers when no symbol file is provided.

The MCP Server and AI-Assisted Debugging

Gearboy 3.8.x includes an embedded MCP server, documented in MCP_README.md in the repository. The MCP server exposes tools for AI assistants including GitHub Copilot, Claude, Codex, and similar tools. The README lists the capabilities as execution control, memory inspection, hardware status queries, rewind, and more.

The practical use case is AI-assisted Game Boy development: a developer loads a ROM in Gearboy, connects an AI assistant through the MCP protocol, and uses the assistant to inspect memory at specific addresses, step through execution, or analyze hardware state without switching between tools. This is a genuinely unusual feature for an emulator; most emulators stop at a GUI debugger.

The repository includes a .agents folder and a skills folder, suggesting the MCP integration is intended to support structured AI workflows. The .devcontainer folder and .vscode folder indicate that the project is set up for development inside a container and in Visual Studio Code.

The MCP server is available on all platforms (the MCPB row in the downloads table), which is confirmed in the README by the presence of MCP_README.md as a separate documentation file.

Gearboy vs. mGBA and gambatte

The most common alternatives mentioned in search data for Gearboy are mGBA and gambatte.

mGBA is a Game Boy Advance emulator that also handles Game Boy and Game Boy Color games. Its primary focus is GBA accuracy; the GBC mode is functional but not its main design target. Gearboy, by contrast, focuses entirely on Game Boy and Game Boy Color hardware, which gives it room to implement a more thorough debugger and a more detailed list of mapper types for the original hardware generation.

gambatte is another accuracy-focused Game Boy Color emulator. It is notable for its high accuracy on GBC hardware and is commonly used as a libretro core. Gearboy and gambatte occupy similar space in terms of accuracy goals, but Gearboy adds the MCP server, the built-in visual debugger, Super Game Boy support, and the link cable emulation that gambatte does not expose.

The choice between Gearboy and gambatte for libretro use depends largely on whether the MCP server and debugger matter for your use case. For pure playback accuracy, both are viable. For development and debugging workflows, Gearboy's built-in tooling and MCP integration are a concrete difference.

The GPL-3.0 license means that modifications to Gearboy's source must be distributed under the same license if the binary is distributed.

Editorial conclusion

Gearboy is the right choice for developers who need a Game Boy emulator that exposes hardware internals through a debugger or an MCP server, and for RetroArch users who want a Gearboy libretro core. Casual players who just want to load ROMs on Android or iOS should note that Gearboy does not offer native Android or iOS apps: the RetroArch core covers those platforms via the RetroArch frontend. Before installing on macOS via Homebrew, run brew trust --tap drhelius/geardome if Homebrew prompts you to trust the third-party tap, as documented in the README.

Frequently asked questions

Official sources

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