Gearboy MCP — 使用場景, 安裝 & 即時演示

為什麼要用

核心特性

Embedded MCP server with stdio and HTTP transport for AI-assisted debugging
Advanced debugger: JIT disassembler, CPU/memory breakpoints, trace logging
VRAM viewer with tile, sprite, and palette inspection
Supports MBC1-7, HuC-1/3, MMM01, Pocket Camera, TAMA5 cartridge types
LCD ghosting and dot matrix visual effects mimicking original hardware

即時演示

實際使用效果

gearboy-2.replay ▶ 就緒

0/0

安裝

選擇你的客戶端

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

開啟 Claude Desktop → Settings → Developer → Edit Config。儲存後重啟應用。

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

Cursor 使用與 Claude Desktop 相同的 mcpServers 格式。專案級設定優先於全域。

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

點擊 Cline 側欄中的 MCP Servers 圖示，然後選 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

格式與 Claude Desktop 相同。重啟 Windsurf 生效。

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "gearboy-2",
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  ]
}

Continue 使用伺服器物件陣列，而非映射。

~/.config/zed/settings.json

{
  "context_servers": {
    "gearboy-2": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/drhelius/Gearboy"
        ]
      }
    }
  }
}

加入 context_servers。Zed 儲存後熱重載。

claude mcp add gearboy-2 -- TODO 'See README: https://github.com/drhelius/Gearboy'

一行命令搞定。用 claude mcp list 驗證，claude mcp remove 移除。

使用場景

實戰用法： Gearboy

How to debug a Game Boy ROM with AI assistance using Gearboy

👤 Homebrew Game Boy developers and ROM hackers ⏱ ~30 min intermediate

何時使用： You're developing a Game Boy homebrew ROM and need to debug runtime issues.

前置條件

Gearboy built with MCP support — Build from source following the GitHub README
A Game Boy ROM file (.gb or .gbc) — Your own homebrew ROM or a ROM you legally own

步驟

Load ROM and connect

Connect to the Gearboy MCP server and load my ROM. Show me the current CPU state and disassembly at the program counter.✓ 已複製

→ CPU registers, flags, and disassembled instructions at PC
Set a breakpoint and investigate

Set a breakpoint at address 0x0150 (after the header). Step through execution and explain what each instruction does.✓ 已複製

→ Step-by-step execution with instruction explanations
Inspect memory

Show me the contents of WRAM from 0xC000 to 0xC0FF. Are there any recognizable data structures?✓ 已複製

→ Memory dump with analysis of data patterns

結果： A clear understanding of how the ROM executes, with bugs identified and explained.

注意事項

Breakpoints on frequently-hit addresses slow execution dramatically — Use conditional breakpoints or set them only when you're close to the bug

搭配使用： filesystem

Learn Game Boy architecture interactively with AI and Gearboy

👤 Students learning retro console hardware and assembly ⏱ ~45 min intermediate

何時使用： You want to understand how the Game Boy CPU, memory, and graphics work hands-on.

前置條件

Gearboy with MCP server — Build from source
A simple test ROM — Use a homebrew test ROM or Blargg's test ROMs

步驟

Explore the memory map

Show me the Game Boy memory map. Read the ROM header at 0x0100-0x014F and explain each field.✓ 已複製

→ Annotated header with title, cartridge type, ROM/RAM sizes
Watch VRAM in action

Step through the VBlank interrupt handler and explain how tiles are loaded into VRAM.✓ 已複製

→ Step-by-step explanation of tile loading with VRAM state

結果： Hands-on understanding of Game Boy hardware through interactive exploration.

注意事項

Assembly can be overwhelming for beginners — Start with simple test ROMs that exercise one hardware feature at a time

組合

與其他 MCP 搭配，撬動十倍槓桿

gearboy-2 + filesystem

Export memory dumps and debug logs for offline analysis

Dump the entire VRAM contents to a file and annotate the tile data layout.✓ 已複製

工具

此 MCP 暴露的能力

工具	輸入參數	何時呼叫
pause/resume/step	none / step_count?	Control emulator execution
read_memory	address: int, size: int	Read emulator memory at any address
write_memory	address: int, data: bytes	Write to emulator memory
set_breakpoint	address: int, type?: str	Set a CPU or memory breakpoint
disassemble	address: int, count: int	Disassemble instructions at an address
get_cpu_state	none	Get current CPU registers and flags

成本與限制

運行它的成本

API 配額: N/A — fully local
每次呼叫 Token 數: 100–500 tokens per debug command
費用: Free and open source (MIT license)
提示: Use targeted memory reads instead of full dumps to keep token usage low.

安全

權限、密鑰、影響範圍

憑證儲存： N/A

資料出站： Fully local — no network calls

故障排查

常見錯誤與修復

MCP server not responding

Ensure Gearboy was built with MCP support enabled. Check that the server port (default 7777) is not in use.

驗證： curl http://localhost:7777/health

ROM fails to load

Verify the ROM file is a valid .gb or .gbc file. Check the file isn't corrupted.

驗證： Check the ROM header with a hex editor

Breakpoint never hits

Verify the address is in the execution path. Use the disassembler to check if code actually runs at that address.

驗證： Disassemble around the target address

替代方案

Gearboy 對比其他方案

替代方案	何時用它替代	權衡
Geargrafx	You want to debug PC Engine / TurboGrafx-16 ROMs instead of Game Boy	Different console, same MCP-enabled emulator approach by the same developer

Gearboy

為什麼要用

核心特性

即時演示

實際使用效果

安裝

選擇你的客戶端

使用場景

實戰用法： Gearboy

How to debug a Game Boy ROM with AI assistance using Gearboy

前置條件

步驟

注意事項

Learn Game Boy architecture interactively with AI and Gearboy

前置條件

步驟

注意事項

組合

與其他 MCP 搭配，撬動十倍槓桿

工具

此 MCP 暴露的能力

成本與限制

運行它的成本

安全

權限、密鑰、影響範圍

故障排查

常見錯誤與修復

替代方案

Gearboy 對比其他方案

更多

資源