Skip to content
ReviewRamble

The weekly brief

AI, reviewed, in your inbox.

  • New reviews of tools, models, MCP servers and repos, with the verdict up front
  • Re-checked prices and ratings when something changes
  • New analysis pieces as they are published

Models, agents, MCP servers and the tools actually worth your time.

One email a week. Unsubscribe with the link in any brief. How we use your email

Gearboy

Game Boy and Game Boy Color emulator with a built-in MCP server: 76 debugger tools for breakpoints, memory, disassembly and rewind.

Reviewed by ReviewRamble editors · Updated

Setup docs Open source

Share this page:XLinkedInFacebookRedditWhatsAppEmail

Our rating

4.2/5

A mature, accurate emulator whose MCP server hands a full debugger to an agent, with sensible network defaults and full write access to the running game.

What is Gearboy?

Gearboy is an open-source Game Boy, Game Boy Color and Super Game Boy emulator by the developer drhelius, written in C++, whose repository dates from 2012. Since version 3.8.0 in March 2026, which also rebuilt the debugger, it ships an MCP server inside the emulator itself, so an agent such as Claude Code or Codex can pause a game, step SM83 instructions, read and write memory, set breakpoints, inspect the LCD and audio hardware, capture screenshots and drive the controller while the debugger GUI shows the same state.

The repository has about 1,220 stars, is licensed GPL-3.0 and released 3.8.21 on 15 November 2026, with commits the same week. Desktop builds cover Windows, macOS, Linux and BSD; MCP Bundles (.mcpb) for six platform and architecture combinations are published to the MCP Registry, and two Agent Skills cover debugging and ROM hacking.

How to install Gearboy

claude mcp add --transport stdio --scope user gearboy -- /path/to/gearboy --mcp-stdio

Is Gearboy worth it?

The MCP server is a front end to a real debugger rather than a thin shim. The MCP README lists 76 tools in 12 groups: execution control down to single instructions and frame steps, CPU registers, reads and writes across ROM banks, VRAM, WRAM, OAM and IO, memory search in the style of a cheat finder, disassembly with symbols and bookmarks, a call stack, a trace logger, a per-function profiler with cycle counts, rewind seeking, save states, cheats and controller macros. Symbol files from RGBDS, GBDK-2020, WLA-DX and other toolchains load automatically next to the ROM, which is what makes the disassembly readable to a model.

A list that long costs context in every session, and the --mcp-router flag addresses it: 12 high-frequency tools stay direct and the rest are found through five discovery tools such as search_tools and get_tool_info. The default exposes everything directly, because clients like Claude Code already defer tool schemas.

On exposure, the defaults are careful. Stdio is the recommended transport and opens no port. HTTP mode, started with --mcp-http or from the MCP menu, listens on 127.0.0.1:7777/mcp; it can run there without a token, but any wildcard or non-loopback address requires GEARBOY_MCP_HTTP_TOKEN as a bearer token and the server refuses to start without it. Host and Origin headers are matched to the real destination address to block DNS rebinding. Two limits are worth knowing. Every HTTP client controls the same emulator instance, so concurrent agents can undo each other's pauses, breakpoints and memory writes; the README suggests one headless instance per agent on its own port. And several tools touch the disk: load_media and load_state_file read any path the process can reach, while save_state_file, start_video_recording and the trace logger write files, the last up to 1 GB or unbounded if asked.

The main competition is general reverse-engineering servers such as Ghidra's, which read a ROM statically; Gearboy runs it, with the hardware state a static tool cannot see. Against c64bridge, which does similar work for the Commodore 64 through external emulators, it has the advantage of one maintainer owning both the emulator and its server. That same single-maintainer structure is the long-term risk, though the release cadence (three releases since 24 October) and three open issues suggest it is well kept.

Where it earns its place

  • A homebrew developer shipping a GBDK-2020 game

    Find the routine that drops frames in a busy level

    Load the ROM with its symbol file, have the agent run the profiler for a few seconds and rank functions by cycles per frame, then step through the worst one. Free; it replaces an evening of manual breakpointing.

  • A fan translator working on a Japanese Game Boy Color RPG

    Locate the text tables and the routine that prints dialogue

    Ask the agent to search memory for known strings, set read breakpoints on the matches and follow the call stack back to the print routine, adding symbols as it goes. The gearboy-romhacking skill describes this workflow.

  • A lecturer teaching a retro computing architecture module

    Show students what the CPU and LCD do during one frame

    Run Gearboy with the GUI open while the agent steps frames and explains LCD registers, interrupts and sprite tables; changes the agent makes appear in the debugger windows at the same time.

Before you commit

Setup
Download a desktop build or run brew install --cask drhelius/geardome/gearboy, then register it: claude mcp add --transport stdio --scope user gearboy -- /path/to/gearboy --mcp-stdio (codex mcp add works the same way). The client launches the emulator when a session starts.
Integrations
76 tools in 12 groups, an optional router mode with five discovery tools, headless mode for machines without a display, MCPB bundles in the MCP Registry and two Agent Skills installed with npx skills add drhelius/gearboy.
Data and privacy
Runs locally; game memory, screenshots and disassembly go to your model provider. No account or network service. HTTP mode listens on 127.0.0.1:7777 by default; non-loopback binds need GEARBOY_MCP_HTTP_TOKEN. Tools can read ROMs and state files from any path and write save states, AVI recordings and trace logs to disk.
Cost at scale
Free under GPL-3.0; the only cost is model usage, which grows with long trace logs and frequent screenshots.
Limits
Concurrent HTTP clients interfere with each other on one instance. The full tool list is large without --mcp-router. Trace logs can reach 1 GB, or more if set to unbounded. On Windows the Visual C++ Redistributable and OpenGL Compatibility Pack may be needed.

What’s good

  • 76 tools over a full debugger, profiler and rewind
  • Stdio by default; HTTP binds to loopback
  • Non-loopback HTTP refuses to start without a token
  • Packaged builds, Homebrew cask and MCPB bundles

What’s not

  • All HTTP clients share one emulator instance
  • File tools read and write any reachable path
  • Game Boy family only
  • One developer writes almost all commits

Best for

Homebrew Game Boy developers, ROM hackers and translators who want an agent to trace, profile and patch a running game.

Gearboy alternatives

Gearboy: common questions

Is Gearboy worth it?
A mature, accurate emulator whose MCP server hands a full debugger to an agent, with sensible network defaults and full write access to the running game. We rate it 4.2 out of 5.
How much does Gearboy cost?
Free and open source (GPL-3.0). Development is funded by GitHub Sponsors.
What are the downsides of Gearboy?
All HTTP clients share one emulator instance; file tools read and write any reachable path; game Boy family only; one developer writes almost all commits.
Who is Gearboy best for?
Homebrew Game Boy developers, ROM hackers and translators who want an agent to trace, profile and patch a running game.
How much does Gearboy cost for a team or in production?
Free under GPL-3.0; the only cost is model usage, which grows with long trace logs and frequent screenshots.
Is Gearboy safe for company data?
Runs locally; game memory, screenshots and disassembly go to your model provider. No account or network service. HTTP mode listens on 127.0.0.1:7777 by default; non-loopback binds need GEARBOY_MCP_HTTP_TOKEN. Tools can read ROMs and state files from any path and write save states, AVI recordings and trace logs to disk.
What are the best Gearboy alternatives?
The closest alternatives we have reviewed are C64 Bridge, GhidraMCP and x64dbg-MCP Server.

Answers checked Nov 16, 2026.

Make Gearboy? Show this rating on your siteGearboy rated 4.2 out of 5 on ReviewRamble