/ 目錄 / 演練場 / Gearboy
● 社群 drhelius ⚡ 即開即用

Gearboy

作者 drhelius · drhelius/Gearboy

Game Boy / Game Boy Color 模擬器具有嵌入式 MCP 伺服器,用於 AI 輔助偵錯和 ROM 分析。

Gearboy 是一款跨平台 Game Boy、Game Boy Color 和 Super Game Boy 模擬器,採用 C++ 編寫,並具有嵌入式 MCP 伺服器。 AI代理可以控制執行(暫停、單步、恢復)、檢查記憶體、設定斷點、反彙編程式碼以及即時監控硬體狀態。 支援 stdio 和 HTTP 傳輸(連接埠 7777)。 在 macOS、Windows、Linux、BSD 和 RetroArch 上運行。

為什麼要用

核心特性

即時演示

實際使用效果

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

如何使用 Gearboy 在 AI 輔助下調試 Game Boy ROM

👤 Homebrew Game Boy 開發者和 ROM 駭客 ⏱ ~30 min intermediate

何時使用: 您正在開發 Game Boy 自製 ROM 並且需要調試運行時問題。

前置條件
  • Gearboy 在 MCP 支持下構建 — 依照 GitHub README 從原始碼構建
  • Game Boy ROM 檔案(.gb 或 .gbc) — 您自己的自製 ROM 或您合法擁有的 ROM
步驟
  1. 載入ROM並連接
    連接到 Gearboy MCP 伺服器並載入我的 ROM。 在程式計數器上顯示目前的 CPU 狀態和反組譯。✓ 已複製
    → PC 上的 CPU 暫存器、標誌和反組譯指令
  2. 設定斷點並進行調查
    在位址 0x0150(標頭之後)處設定斷點。 單步執行並解釋每條指令的作用。✓ 已複製
    → 逐步執行並附有說明說明
  3. 檢查記憶體
    顯示 WRAM 從 0xC000 到 0xC0FF 的內容。 有沒有可辨識的資料結構?✓ 已複製
    → 記憶體轉儲以及資料模式分析

結果: 清楚地了解 ROM 如何執行,並識別和解釋錯誤。

注意事項
  • 頻繁命中位址上的斷點會顯著降低執行速度 — 使用條件斷點或僅在接近錯誤時設定它們
搭配使用: filesystem

與 AI 和 Gearboy 互動學習 Game Boy 架構

👤 學生學習復古控制台硬體和組裝 ⏱ ~45 min intermediate

何時使用: 您想親自了解 Game Boy CPU、記憶體和顯示卡的工作原理。

前置條件
  • 帶有 MCP 伺服器的 Gearboy — 從原始碼構建
  • 一個簡單的測試ROM — 使用自製測試 ROM 或 Blargg 的測試 ROM
步驟
  1. 探索記憶體映射
    顯示 Game Boy 記憶體映射。 讀取 0x0100-0x014F 處的 ROM 標頭並解釋每個欄位。✓ 已複製
    → 帶有標題、盒帶類型、ROM/RAM 大小的註釋標題
  2. 觀看 VRAM 的運作情況
    單步執行 VBlank 中斷處理程序並解釋如何將圖塊載入到 VRAM 中。✓ 已複製
    → 使用 VRAM 狀態載入圖塊的逐步說明

結果: 透過互動探索親身了解 Game Boy 硬體。

注意事項
  • 組裝對於初學者來說可能會讓人不知所措 — 從一次測試一項硬體功能的簡單測試 ROM 開始

組合

與其他 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? 控制模擬器執行 0
read_memory address: int, size: int 讀取任意位址的模擬器內存 0
write_memory address: int, data: bytes 寫入模擬器內存 0
set_breakpoint address: int, type?: str 設定CPU或記憶體斷點 0
disassemble address: int, count: int 某個位址處的反組譯指令 0
get_cpu_state none 取得當前CPU暫存器和標誌 0

成本與限制

運行它的成本

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 對比其他方案

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

更多

資源

📖 閱讀 GitHub 上的官方 README

🐙 查看未解決的 issue

🔍 瀏覽全部 400+ MCP 伺服器和 Skills