Gearboy MCP — Installieren & Live-Demo

Warum nutzen

Hauptfunktionen

Eingebetteter MCP-Server mit Standard- und HTTP-Transport für KI-gestütztes Debugging
Erweiterter Debugger: JIT-Disassembler, CPU-/Speicher-Haltepunkte, Trace-Protokollierung
VRAM-Viewer mit Kachel-, Sprite- und Paletteninspektion
Unterstützt die Patronentypen MBC1-7, HuC-1/3, MMM01, Pocket Camera und TAMA5
LCD-Geisterbilder und visuelle Dot-Matrix-Effekte imitieren Original-Hardware

Live-Demo

In der Praxis

gearboy-2.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": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

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

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

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

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

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

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

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "gearboy-2": {
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  }
}

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

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "gearboy-2",
      "command": "TODO",
      "args": [
        "See README: https://github.com/drhelius/Gearboy"
      ]
    }
  ]
}

Continue nutzt ein Array von Serverobjekten statt einer Map.

~/.config/zed/settings.json

{
  "context_servers": {
    "gearboy-2": {
      "command": {
        "path": "TODO",
        "args": [
          "See README: https://github.com/drhelius/Gearboy"
        ]
      }
    }
  }
}

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

claude mcp add gearboy-2 -- TODO 'See README: https://github.com/drhelius/Gearboy'

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

Anwendungsfälle

Praxisnahe Nutzung: Gearboy

So debuggen Sie ein Game Boy ROM mit KI-Unterstützung mithilfe von Gearboy

👤 Homebrew-Game-Boy-Entwickler und ROM-Hacker ⏱ ~30 min intermediate

Wann einsetzen: Sie entwickeln ein Homebrew-ROM für den Game Boy und müssen Laufzeitprobleme beheben.

Voraussetzungen

Gearboy mit MCP-Unterstützung gebaut — Erstellen Sie aus dem Quellcode und folgen Sie dabei der GitHub-README-Datei
Eine Game Boy ROM-Datei (.gb oder .gbc) — Ihr eigenes Homebrew-ROM oder ein ROM, das Sie rechtmäßig besitzen

Ablauf

ROM laden und verbinden

Stellen Sie eine Verbindung zum Gearboy MCP-Server her und laden Sie mein ROM. Zeigen Sie mir den aktuellen CPU-Zustand und die Demontage am Programmschalter.✓ Kopiert

→ CPU-Register, Flags und disassemblierte Anweisungen am PC
Setzen Sie einen Haltepunkt und untersuchen Sie die Situation

Setzen Sie einen Haltepunkt an der Adresse 0x0150 (nach dem Header). Gehen Sie die Ausführung Schritt für Schritt durch und erklären Sie, was jede Anweisung bewirkt.✓ Kopiert

→ Schritt-für-Schritt-Anleitung mit Anleitungserklärungen
Speicher überprüfen

Zeigen Sie mir den Inhalt des WRAM von 0xC000 bis 0xC0FF. Sind Datenstrukturen erkennbar?✓ Kopiert

→ Speicherauszug mit Analyse von Datenmustern

Ergebnis: Ein klares Verständnis der Funktionsweise des ROM, wobei Fehler identifiziert und erklärt werden.

Fallstricke

Haltepunkte an häufig aufgerufenen Adressen verlangsamen die Ausführung erheblich — Verwenden Sie bedingte Haltepunkte oder legen Sie sie nur fest, wenn Sie sich dem Fehler nähern

Kombinieren mit: filesystem

Lernen Sie die Game Boy-Architektur interaktiv mit KI und Gearboy

👤 Schüler lernen Retro-Konsolenhardware und -montage ⏱ ~45 min intermediate

Wann einsetzen: Sie möchten verstehen, wie die CPU, der Speicher und die Grafik des Game Boy praktisch funktionieren.

Voraussetzungen

Gearboy mit MCP-Server — Aus dem Quellcode erstellen
Ein einfaches Test-ROM — Verwenden Sie ein Homebrew-Test-ROM oder Blarggs Test-ROMs

Ablauf

Entdecken Sie die Speicherkarte

Zeig mir die Game Boy-Speicherkarte. Lesen Sie den ROM-Header bei 0x0100-0x014F und erklären Sie jedes Feld.✓ Kopiert

→ Kommentierte Kopfzeile mit Titel, Kassettentyp und ROM/RAM-Größen
Sehen Sie VRAM in Aktion

Gehen Sie den VBlank-Interrupt-Handler Schritt für Schritt durch und erklären Sie, wie Kacheln in den VRAM geladen werden.✓ Kopiert

→ Schritt-für-Schritt-Erklärung zum Laden von Kacheln mit VRAM-Status

Ergebnis: Praktisches Verständnis der Game Boy-Hardware durch interaktive Erkundung.

Fallstricke

Der Zusammenbau kann für Anfänger überwältigend sein — Beginnen Sie mit einfachen Test-ROMs, die jeweils eine Hardwarefunktion ausführen

Kombinationen

Mit anderen MCPs für 10-fache Wirkung

gearboy-2 + filesystem

Exportieren Sie Speicherauszüge und Debug-Protokolle für die Offline-Analyse

Speichern Sie den gesamten VRAM-Inhalt in einer Datei und kommentieren Sie das Kacheldatenlayout.✓ Kopiert

Werkzeuge

Was dieses MCP bereitstellt

Werkzeug	Eingaben	Wann aufrufen
pause/resume/step	none / step_count?	Steuern Sie die Ausführung des Emulators
read_memory	address: int, size: int	Emulatorspeicher an einer beliebigen Adresse lesen
write_memory	address: int, data: bytes	Schreiben Sie in den Emulatorspeicher
set_breakpoint	address: int, type?: str	Legen Sie einen CPU- oder Speicher-Haltepunkt fest
disassemble	address: int, count: int	Demontageanleitung an einer Adresse
get_cpu_state	none	Aktuelle CPU-Register und Flags abrufen

Kosten & Limits

Was der Betrieb kostet

API-Kontingent: N/A – vollständig lokal
Tokens pro Aufruf: 100–500 Token pro Debug-Befehl
Kosten in €: Kostenlos und Open Source (MIT-Lizenz)
Tipp: Verwenden Sie gezielte Speicherlesevorgänge anstelle vollständiger Dumps, um die Token-Nutzung niedrig zu halten.

Sicherheit

Rechte, Secrets, Reichweite

Credential-Speicherung: N / A

Datenabfluss: Vollständig lokal – keine Netzwerkanrufe

Fehlerbehebung

Häufige Fehler und Lösungen

MCP server not responding

Stellen Sie sicher, dass Gearboy mit aktivierter MCP-Unterstützung erstellt wurde. Stellen Sie sicher, dass der Server-Port (Standard 7777) nicht verwendet wird.

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

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

Prüfen: Disassemble around the target address

Alternativen

Gearboy vs. andere

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

Mehr

Ressourcen

📖 Offizielle README auf GitHub lesen

🐙 Offene Issues ansehen

🔍 Alle 400+ MCP-Server und Skills durchsuchen