Skip to content
MCP server

Gearboy MCP Server

Game Boy and Game Boy Color emulator with a built-in MCP server for AI-assisted debugging

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
Windows, macOS, Linux
Runs
Locally
Version
3.8.21
Listing updated
today

Similar MCP servers

About Gearboy MCP Server

Gearboy MCP Server is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

Gearboy is an open-source C++ emulator for the Game Boy, Game Boy Color and Super Game Boy, and the MCP server is part of the app itself rather than a separate service. Start the emulator with a flag such as --mcp-stdio, or --mcp-http (default port 7777, bound to 127.0.0.1), and a client like Claude Code or Codex can control it. The README says the tools cover execution control, memory inspection, hardware status and rewind, and a --mcp-router option enables compact tool routing.

The emulator behind it is a full debugger: disassembler, CPU and memory breakpoints, memory editor, trace logger, I/O inspector and a VRAM viewer for tiles, sprites, backgrounds and palettes. It loads debug symbols in RGBDS, GBDK-2020, WLA-DX, no$gmb and SDCC formats, which suits homebrew development. A --headless mode runs without a GUI when MCP or link cable is used.

Other features include save states with rewind, run-ahead, Game Genie and GameShark cheats, a programmable shader chain, a local two-instance link cable and many cartridge mappers. It runs on Windows, macOS, Linux and BSD, and as a RetroArch core. Downloads include per-platform MCPB bundles.

Install

Run in a terminal

claude mcp add gearboy -- npx -y https://github.com/drhelius/gearboy/releases/download/3.8.21/Gearboy-3.8.21-mcpb-macos-arm64.mcpb

Add to claude_desktop_config.json

{
  "mcpServers": {
    "gearboy": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/drhelius/gearboy/releases/download/3.8.21/Gearboy-3.8.21-mcpb-macos-arm64.mcpb"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "gearboy": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/drhelius/gearboy/releases/download/3.8.21/Gearboy-3.8.21-mcpb-macos-arm64.mcpb"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "gearboy": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/drhelius/gearboy/releases/download/3.8.21/Gearboy-3.8.21-mcpb-macos-arm64.mcpb"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "gearboy": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/drhelius/gearboy/releases/download/3.8.21/Gearboy-3.8.21-mcpb-macos-arm64.mcpb"
      ]
    }
  }
}

Add to your client's MCP settings (most use this shape)

{
  "mcpServers": {
    "gearboy": {
      "command": "npx",
      "args": [
        "-y",
        "https://github.com/drhelius/gearboy/releases/download/3.8.21/Gearboy-3.8.21-mcpb-macos-arm64.mcpb"
      ]
    }
  }
}

Using several servers? Build one config file with the MCP config generator.

What it does

Embedded MCP server
Start the emulator with stdio or HTTP MCP transport for AI clients.
Full debugger
Disassembler, breakpoints, memory editor, trace logger and VRAM viewer.
Symbol support
Loads RGBDS, GBDK-2020, WLA-DX, no$gmb and SDCC symbols.
Headless mode
Runs without a GUI when driven by MCP or link cable.
Save states and rewind
Includes previews, rewind and run-ahead.
Cartridge coverage
Supports many mappers and Game Boy Color and Super Game Boy.
Cross-platform
Builds for Windows, macOS, Linux, BSD and as a libretro core.

Good for

  • Have an AI assistant step through Game Boy code and inspect memory
  • Debug a homebrew ROM with symbol files
  • Trace graphics bugs using the VRAM viewer
  • Script emulator runs headlessly for testing
  • Play Game Boy games with cheats and shaders

Pricing

Open source

Free and open source; sponsorship optional

Gearboy MCP Server FAQ

How do I start the MCP server?

Launch gearboy with --mcp-stdio or --mcp-http; HTTP defaults to 127.0.0.1 port 7777.

Is a GUI required?

No, --headless runs without one when MCP or link cable is used.

Which platforms are supported?

Windows, macOS, Linux and BSD as a standalone app, plus RetroArch on many more.

Is it open source?

The README describes it as an open source project supported by sponsors.

Is Gearboy MCP Server free?

Yes. Gearboy MCP Server is open source, so you can use and self-host it for free.

How do I add Gearboy MCP Server to Claude Code?

Run this command in your terminal: claude mcp add gearboy -- npx -y https://github.com/drhelius/gearboy/releases/download/3.8.21/Gearboy-3.8.21-mcpb-macos-arm64.mcpb

What are the best alternatives to Gearboy MCP Server?

The closest alternatives to Gearboy MCP Server are REA, Context7, Chrome DevTools MCP, Codebase Memory and GitHub.

Where this comes from

  • Description: written from the project's README.
  • Install steps: from the official MCP Registry entry.

How AIPoweredBot checks servers