/ 디렉터리 / 플레이그라운드 / Gearboy
● 커뮤니티 drhelius ⚡ 바로 사용

Gearboy

제작: drhelius · drhelius/Gearboy

AI 지원 디버깅 및 ROM 분석을 위한 MCP 서버가 내장된 Game Boy/Game Boy Color 에뮬레이터입니다.

Gearboy는 MCP 서버가 내장된 C++로 작성된 크로스 플랫폼 Game Boy, Game Boy Color 및 Super Game Boy 에뮬레이터입니다. 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을 개발 중이며 런타임 문제를 디버깅해야 합니다.

사전 조건
  • MCP 지원으로 구축된 Gearboy — GitHub README에 따라 소스에서 빌드
  • Game Boy ROM 파일(.gb 또는 .gbc) — 자신만의 홈브류 ROM 또는 법적으로 소유한 ROM
흐름
  1. ROM을 로드하고 연결
    Gearboy MCP 서버에 연결하고 내 ROM을 로드합니다. 프로그램 카운터에서 현재 CPU 상태와 분해를 보여주세요.✓ 복사됨
    → PC의 CPU 레지스터, 플래그 및 디스어셈블된 명령어
  2. 중단점 설정 및 조사
    주소 0x0150(헤더 뒤)에 중단점을 설정합니다. 실행을 단계별로 설명하고 각 명령어의 기능을 설명합니다.✓ 복사됨
    → 지침 설명과 함께 단계별 실행
  3. 메모리 검사
    0xC000부터 0xC0FF까지 WRAM의 내용을 보여주세요. 인식 가능한 데이터 구조가 있습니까?✓ 복사됨
    → 데이터 패턴 분석을 통한 메모리 덤프

결과: 버그 식별 및 설명과 함께 ROM이 실행되는 방식에 대한 명확한 이해.

함정
  • 자주 적중되는 주소의 중단점으로 인해 실행 속도가 크게 느려집니다. — 조건부 중단점을 사용하거나 버그에 가까워졌을 때만 설정하세요.
함께 쓰기: filesystem

AI 및 Gearboy를 통해 대화형으로 Game Boy 아키텍처를 알아보세요.

👤 복고풍 콘솔 하드웨어 및 조립을 배우는 학생들 ⏱ ~45 min intermediate

언제 쓸까: Game Boy CPU, 메모리 및 그래픽이 직접 작동하는 방식을 이해하고 싶습니다.

사전 조건
  • MCP 서버를 갖춘 Gearboy — 소스에서 빌드
  • 간단한 테스트 ROM — 홈브류 테스트 ROM 또는 Blargg의 테스트 ROM을 사용하세요.
흐름
  1. 메모리 맵 탐색
    게임보이 메모리 맵을 보여주세요. 0x0100-0x014F의 ROM 헤더를 읽고 각 필드에 대해 설명하십시오.✓ 복사됨
    → 제목, 카트리지 유형, ROM/RAM 크기가 포함된 주석이 달린 헤더
  2. VRAM 작동 모습 보기
    VBlank 인터럽트 처리기를 단계별로 진행하고 타일이 VRAM에 로드되는 방법을 설명합니다.✓ 복사됨
    → VRAM 상태를 사용한 타일 로딩에 대한 단계별 설명

결과: 대화형 탐색을 통해 Game Boy 하드웨어를 직접 이해합니다.

함정
  • 조립은 초보자에게 부담스러울 수 있습니다 — 한 번에 하나의 하드웨어 기능을 실행하는 간단한 테스트 ROM으로 시작하십시오.

조합

다른 MCP와 조합해 10배 효율

gearboy-2 + filesystem

오프라인 분석을 위해 메모리 덤프 및 디버그 로그 내보내기

전체 VRAM 콘텐츠를 파일로 덤프하고 타일 데이터 레이아웃에 주석을 답니다.✓ 복사됨

도구

이 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 쿼터
해당 없음 — 완전 로컬
호출당 토큰
디버그 명령당 토큰 100~500개
금액
무료 및 오픈 소스(MIT 라이센스)
전체 덤프 대신 대상 메모리 읽기를 사용하여 토큰 사용량을 낮게 유지합니다.

보안

권한, 시크릿, 파급범위

자격 증명 저장: 해당 없음
데이터 외부 송신: 완전 로컬 — 네트워크 호출 없음

문제 해결

자주 발생하는 오류와 해결

MCP server not responding

MCP 지원이 활성화된 상태로 Gearboy가 구축되었는지 확인하세요. 서버 포트(기본값 7777)가 사용 중이 아닌지 확인하세요.

확인: curl http://localhost:7777/health
ROM fails to load

ROM 파일이 유효한 .gb 또는 .gbc 파일인지 확인하십시오. 파일이 손상되지 않았는지 확인하세요.

확인: Check the ROM header with a hex editor
Breakpoint never hits

주소가 실행 경로에 있는지 확인하십시오. 디스어셈블러를 사용하여 해당 주소에서 코드가 실제로 실행되는지 확인하세요.

확인: Disassemble around the target address

대안

Gearboy 다른 것과 비교

대안언제 쓰나단점/장점
GeargrafxGame Boy 대신 PC 엔진/TurboGrafx-16 ROM을 디버깅하고 싶습니다.동일한 개발자의 다른 콘솔, 동일한 MCP 지원 에뮬레이터 접근 방식

더 보기

리소스

📖 GitHub에서 공식 README 읽기

🐙 열린 이슈 보기

🔍 400+ MCP 서버 및 Skills 전체 보기