Gearsystem MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

Embedded MCP server — one binary is emulator + debugger + MCP
stdio and HTTP transports (--mcp-stdio or --mcp-http --mcp-http-port N)
Can run headless via MCP for automated/agent-driven sessions
CPU breakpoints, memory-access breakpoints, step, disassembly
VRAM and palette inspection for graphics debugging

라이브 데모

실제 사용 모습

gearsystem.replay ▶ 준비됨

0/0

설치

클라이언트 선택

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

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

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

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "gearsystem": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "gearsystem",
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearsystem"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "gearsystem": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/drhelius/Gearsystem"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add gearsystem -- TODO 'See README: https://github.com/drhelius/Gearsystem'

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: Gearsystem

Debug a homebrew Master System ROM that crashes on title screen

👤 Retro homebrew developers ⏱ ~30 min advanced

언제 쓸까: Your WLA-DX build runs fine in your head but Gearsystem freezes on the title screen.

사전 조건

Gearsystem built with MCP enabled — Clone drhelius/Gearsystem and build per MCP_README.md
The ROM and its .sym symbol file — Output of your assembler (WLA-DX, asm6 etc.)

흐름

Launch headless and set a breakpoint at the crash point

Launch Gearsystem MCP with my ROM. Set a CPU breakpoint at the label init_vdp and run.✓ 복사됨

→ Execution halts at the breakpoint
Inspect CPU and VRAM state

Show me the Z80 registers and the first 32 bytes of VRAM. Anything look wrong for this point in init?✓ 복사됨

→ Register dump + observations about expected vs actual
Step through and watch a specific memory region

Add a memory-access breakpoint on $C000 and step until something writes there.✓ 복사됨

→ Stops at the offending instruction

결과: A root cause (e.g. VDP register written before VRAM is safe) with the exact instruction address.

함정

Symbols not loaded — addresses are opaque — Make sure .sym matches the exact ROM build; rebuild to align if needed
Timing bug only repros on real hardware, not emulator — Emulator has limits; for bus timing edge cases, test on a real SMS

함께 쓰기: filesystem

Reverse-engineer a ROM you own to document its memory map

👤 Preservationists and devs documenting their own or public-domain ROMs ⏱ ~60 min advanced

언제 쓸까: You're writing a tech analysis article or disassembly and need a memory map.

흐름

Run the ROM and inspect at key moments

Boot the ROM, break at VBlank, dump WRAM at $C000-$DFFF. Then run one frame and dump again.✓ 복사됨

→ Two WRAM snapshots for diffing
Identify likely variables by diffing

Compare the two snapshots. Which addresses changed? What are they likely to be (counters, pointers, sprite positions)?✓ 복사됨

→ Hypothesized variable map with justification

결과: A first-pass memory map you can refine by hand.

함정

Reverse-engineering commercial copyrighted ROMs you don't own is a legal gray area — Only use this on ROMs you own or that are in the public domain. Don't publish RAM maps for commercial ROMs without considering fair-use rules in your jurisdiction

Automate a smoke test for your ROM on every commit

👤 Homebrew devs with a CI pipeline ⏱ ~25 min intermediate

언제 쓸까: You want 'boots to title screen without crashing' as a CI gate.

흐름

Script the MCP session

Write a script that launches Gearsystem MCP headless, runs my ROM for 600 frames, and returns non-zero if the CPU halted on an invalid opcode.✓ 복사됨

→ Shell script with clear exit codes
Wire into CI

Wrap that in a GitHub Actions workflow that runs on every push to main.✓ 복사됨

→ Working CI step

결과: A smoke test that catches regressions before you manually load the ROM.

함께 쓰기: github

조합

다른 MCP와 조합해 10배 효율

gearsystem + github

Debug and commit a fix in one flow

Reproduce issue #12 in my ROM, find the faulting address, open a PR with a one-liner fix in src/vdp.asm.✓ 복사됨

gearsystem + filesystem

Read the .sym file alongside the debugger to translate addresses to labels

Load ./build/game.sym and tell me the label at address $03A7.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
run	(none)	Resume execution after a break	free (local)
pause	(none)	Halt to inspect	free
step	n?: int	Single-step instructions	free
set_breakpoint	address: hex, kind: cpu\|read\|write	Watch for a PC hit or memory access	free
read_memory	address: hex, length: int	Inspect WRAM / VRAM / cart regions	free
disassemble	address: hex, instructions: int	Read code around a PC	free
get_registers	(none)	Any inspection moment	free
dump_vram	start?: hex, length?: int	Graphics debugging	free

비용 및 제한

운영 비용

API 쿼터: None — fully local process
호출당 토큰: Memory dumps can be large; narrow ranges keep responses small
금액: Free, GPL-3.0 licensed
팁: Ask for small memory windows (16-64 bytes) unless you actually need a full page.

보안

권한, 시크릿, 파급범위

자격 증명 저장: None needed

데이터 외부 송신: Runs locally; MCP server binds to stdio or chosen HTTP port

If you expose --mcp-http, bind only to 127.0.0.1 — nothing authenticates the endpoint.
Loaded ROMs can be arbitrary untrusted data; emulator is sandboxed but don't grant the process extra privileges.

문제 해결

자주 발생하는 오류와 해결

MCP flags not recognized

Your build was compiled without MCP support. Rebuild with the flag enabled per MCP_README.md.

확인: gearsystem --help | grep mcp

Breakpoint never hits

Symbol resolution likely off; try using a raw address instead of a label. Confirm ROM is actually loaded.

확인: Use get_registers to confirm PC is moving

HTTP transport refused connection

Check the port isn't in use and the emulator started with --mcp-http --mcp-http-port 7777.

확인: curl http://127.0.0.1:7777/

대안

Gearsystem 다른 것과 비교

대안	언제 쓰나	단점/장점
Emulicious	You want a full GUI debugger for Game Boy/SMS/etc.	No MCP; human-driven only
BizHawk	Multi-system TAS/debugging	Lua-scripted rather than MCP

Gearsystem