Gearsystem MCP — Anwendungsfälle, Installieren & Live-Demo

Warum nutzen

Hauptfunktionen

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

Live-Demo

In der Praxis

gearsystem.replay ▶ bereit

0/0

Installieren

Wählen Sie Ihren Client

~/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
    }
  }
}

Öffne Claude Desktop → Settings → Developer → Edit Config. Nach dem Speichern neu starten.

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

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

Cursor nutzt das gleiche mcpServers-Schema wie Claude Desktop. Projektkonfiguration schlägt die globale.

VS Code → Cline → MCP Servers → Edit

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

Klicken Sie auf das MCP-Servers-Symbol in der Cline-Seitenleiste, dann "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Gleiche Struktur wie Claude Desktop. Windsurf neu starten zum Übernehmen.

~/.continue/config.json

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

Continue nutzt ein Array von Serverobjekten statt einer Map.

~/.config/zed/settings.json

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

In context_servers hinzufügen. Zed lädt beim Speichern neu.

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

Einzeiler. Prüfen mit claude mcp list. Entfernen mit claude mcp remove.

Anwendungsfälle

Praxisnahe Nutzung: Gearsystem

Debug a homebrew Master System ROM that crashes on title screen

👤 Retro homebrew developers ⏱ ~30 min advanced

Wann einsetzen: Your WLA-DX build runs fine in your head but Gearsystem freezes on the title screen.

Voraussetzungen

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.)

Ablauf

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.✓ Kopiert

→ 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?✓ Kopiert

→ 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.✓ Kopiert

→ Stops at the offending instruction

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

Fallstricke

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

Kombinieren mit: 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

Wann einsetzen: You're writing a tech analysis article or disassembly and need a memory map.

Ablauf

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.✓ Kopiert

→ 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)?✓ Kopiert

→ Hypothesized variable map with justification

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

Fallstricke

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

Wann einsetzen: You want 'boots to title screen without crashing' as a CI gate.

Ablauf

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.✓ Kopiert

→ Shell script with clear exit codes
Wire into CI

Wrap that in a GitHub Actions workflow that runs on every push to main.✓ Kopiert

→ Working CI step

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

Kombinieren mit: github

Kombinationen

Mit anderen MCPs für 10-fache Wirkung

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.✓ Kopiert

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.✓ Kopiert

Werkzeuge

Was dieses MCP bereitstellt

Werkzeug	Eingaben	Wann aufrufen	Kosten
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

Kosten & Limits

Was der Betrieb kostet

API-Kontingent: None — fully local process
Tokens pro Aufruf: Memory dumps can be large; narrow ranges keep responses small
Kosten in €: Free, GPL-3.0 licensed
Tipp: Ask for small memory windows (16-64 bytes) unless you actually need a full page.

Sicherheit

Rechte, Secrets, Reichweite

Credential-Speicherung: None needed

Datenabfluss: 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.

Fehlerbehebung

Häufige Fehler und Lösungen

MCP flags not recognized

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

Prüfen: 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.

Prüfen: 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.

Prüfen: curl http://127.0.0.1:7777/

Alternativen

Gearsystem vs. andere

Alternative	Wann stattdessen	Kompromiss
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

Mehr

Ressourcen

📖 Offizielle README auf GitHub lesen

🐙 Offene Issues ansehen

🔍 Alle 400+ MCP-Server und Skills durchsuchen