Gearboy MCP Server
Game Boy and Game Boy Color emulator with a built-in MCP server for AI-assisted debugging
- 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.mcpbAdd 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"
]
}
}
}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"
]
}
}
}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.


