Gearboy

Overview

Gearboy is a cross-platform Game Boy / Game Boy Color / Super Game Boy emulator written in C++ that includes an embedded MCP server for debugging and tooling. The MCP server enables AI-assisted debugging through GitHub Copilot, Claude, Codex and similar agents, providing tools for execution control, memory inspection, breakpoints, disassembly, and hardware status. It also supports Agent Skills that teach AI assistants how to effectively use the emulator for specific tasks like debugging and ROM hacking.

Try asking AI

After installing, here are 6 things you can ask your AI assistant:

• step_instruction

  Execute a single CPU instruction and pause

  Try:Step one instruction forwardTry:Execute next instruction
• run

  Run the emulator until interrupted

  Try:Run the game until pausedTry:Start execution
• pause

  Pause emulator execution

  Try:Pause the emulatorTry:Stop execution
• reset

  Reset the emulator to initial state

  Try:Reset the emulatorTry:Restart the game
• load_rom

  Load a ROM file into the emulator

  Try:Load Pokemon Red ROMTry:Load game.gb file
• read_memory

  Read memory from a specific address

  Try:Read memory at address 0x8000Try:Check value at 0xC000
• write_memory

  Write a value to a specific memory address

  Try:Write 0xFF to address 0x8000Try:Set memory location 0xC000 to 0x42
• set_breakpoint

  Set a breakpoint at a specific address

  Try:Set breakpoint at address 0x8000Try:Break execution when PC is 0x1234
• clear_breakpoint

  Remove a breakpoint at a specific address

  Try:Clear breakpoint at address 0x8000Try:Remove breakpoint at 0x1234
• list_breakpoints

  List all currently set breakpoints

  Try:Show all breakpointsTry:List current breakpoints
• disassemble

  Disassemble instructions at a specific address

  Try:Disassemble code at address 0x8000Try:Show instructions near 0x1234
• get_registers

  Get current CPU register values

  Try:Show current register valuesTry:Display CPU registers

Comparable tools

Installation

{
  "mcpServers": {
    "gearboy": {
      "command": "path/to/gearboy",
      "args": ["--mcp-stdio"]
    }
  }
}

FAQ

What platforms does Gearboy MCP server support?

Gearboy runs on Windows, macOS, Linux, BSD and RetroArch, with the MCP server available across all platforms through stdio or HTTP transport.

How can I use the Agent Skills feature?

Install Agent Skills with `npx skills add drhelius/gearboy` to teach AI assistants how to effectively use the emulator for debugging and ROM hacking tasks.

What debugging tools does the MCP server provide?

The server exposes tools for execution control, memory inspection, breakpoints, disassembly, hardware status, rewind, and more for AI-assisted debugging.

On Hacker News

Recent discussion from the developer community.

• Gearboy, a cross-platform Gameboy emulator (iOS too)▲ 1
  Story by jfoucher · 2022-03-24

Compare Gearboy with