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와 조합해 10배 효율

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
호출당 토큰: 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와 조합해 10배 효율

도구

이 MCP가 노출하는 것

비용 및 제한

운영 비용

보안

권한, 시크릿, 파급범위

문제 해결

자주 발생하는 오류와 해결

대안

Gearboy 다른 것과 비교

더 보기

리소스