# Gearboy MCP Server

> Gearboy MCP Server is an open-source MCP server for developer tools. Game Boy and Game Boy Color emulator with a built-in MCP server for AI-assisted debugging. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** Windows, macOS, Linux, CLI
- **Repository:** https://github.com/drhelius/gearboy
- **MCP Registry name:** io.github.drhelius/gearboy
- **Categories:** [developer tools](https://ai-powered.com/categories/developer-tools), [games and play](https://ai-powered.com/categories/games-and-play)
- **Listing updated:** 2026-11-18

## About

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.

## Features

- **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

## Install

### Claude Code (Terminal)

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

### Claude Desktop (claude_desktop_config.json)

```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"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```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"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```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"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```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"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```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"
      ]
    }
  }
}
```

## 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.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Context7](https://ai-powered.com/mcp/context7): Context7 is a freemium MCP server for developer tools.
- [Chrome DevTools MCP](https://ai-powered.com/mcp/chrome-devtools-mcp-2): Chrome DevTools MCP is an open-source MCP server for browser automation.
- [Codebase Memory](https://ai-powered.com/mcp/codebase-memory): Codebase Memory is an open-source MCP server for knowledge and memory.
- [GitHub](https://ai-powered.com/mcp/github-2): GitHub is an open-source MCP server for developer tools.
- [Serena MCP: the IDE for your agent](https://ai-powered.com/mcp/serena-mcp-the-ide-for-your-agent): Serena MCP: the IDE for your agent is an open-source MCP server for developer tools.
- [awesome-mcp-servers](https://ai-powered.com/mcp/awesome-mcp-servers-2): awesome-mcp-servers is an open-source MCP server for developer tools.
- [XERJ](https://ai-powered.com/mcp/xerj): XERJ is an open-source MCP server for knowledge and memory.

---
Source: https://ai-powered.com/mcp/gearboy-mcp-server
