Gearboy MCP — Installer & Démo en direct

Pourquoi l'utiliser

Fonctionnalités clés

Serveur MCP intégré avec transport stdio et HTTP pour le débogage assisté par l'IA
Débogueur avancé : désassembleur JIT, points d'arrêt CPU/mémoire, journalisation des traces
Visionneuse VRAM avec inspection des tuiles, des sprites et des palettes
Prend en charge les types de cartouches MBC1-7, HuC-1/3, MMM01, Pocket Camera, TAMA5
Effets visuels fantômes LCD et matrice de points imitant le matériel d'origine

Démo en direct

Aperçu en pratique

gearboy-2.replay ▶ prêt

0/0

Installer

Choisissez votre 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"
      ]
    }
  }
}

Ouvrez Claude Desktop → Settings → Developer → Edit Config. Redémarrez après avoir enregistré.

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

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

Cursor utilise le même schéma mcpServers que Claude Desktop. La config projet l'emporte sur la globale.

VS Code → Cline → MCP Servers → Edit

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

Cliquez sur l'icône MCP Servers dans la barre latérale Cline, puis "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

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

Même format que Claude Desktop. Redémarrez Windsurf pour appliquer.

~/.continue/config.json

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

Continue utilise un tableau d'objets serveur plutôt qu'une map.

~/.config/zed/settings.json

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

Ajoutez dans context_servers. Zed recharge à chaud à la sauvegarde.

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

Une seule ligne. Vérifiez avec claude mcp list. Supprimez avec claude mcp remove.

Cas d'usage

Usages concrets : Gearboy

Comment déboguer une ROM Game Boy avec l'assistance de l'IA à l'aide de Gearboy

👤 Développeurs Homebrew Game Boy et pirates ROM ⏱ ~30 min intermediate

Quand l'utiliser : Vous développez une ROM homebrew Game Boy et devez déboguer les problèmes d'exécution.

Prérequis

Gearboy construit avec le support MCP — Construire à partir des sources en suivant le fichier README de GitHub
Un fichier ROM Game Boy (.gb ou .gbc) — Votre propre ROM homebrew ou une ROM que vous possédez légalement

Déroulement

Charger la ROM et se connecter

Connectez-vous au serveur Gearboy MCP et chargez ma ROM. Montrez-moi l'état actuel du processeur et son démontage au compteur du programme.✓ Copié

→ Registres du processeur, indicateurs et instructions démontées sur PC
Définir un point d'arrêt et enquêter

Définissez un point d'arrêt à l'adresse 0x0150 (après l'en-tête). Parcourez l’exécution et expliquez ce que fait chaque instruction.✓ Copié

→ Exécution étape par étape avec explications des instructions
Inspecter la mémoire

Montrez-moi le contenu de la WRAM de 0xC000 à 0xC0FF. Existe-t-il des structures de données reconnaissables ?✓ Copié

→ Vidage de mémoire avec analyse des modèles de données

Résultat : Une compréhension claire de la façon dont la ROM s'exécute, avec des bugs identifiés et expliqués.

Pièges

Les points d'arrêt sur les adresses fréquemment utilisées ralentissent considérablement l'exécution — Utilisez des points d'arrêt conditionnels ou définissez-les uniquement lorsque vous êtes proche du bug

Combiner avec : filesystem

Apprenez l'architecture Game Boy de manière interactive avec l'IA et Gearboy

👤 Étudiants apprenant le matériel et l'assemblage d'une console rétro ⏱ ~45 min intermediate

Quand l'utiliser : Vous souhaitez comprendre comment fonctionnent le processeur, la mémoire et les graphiques de la Game Boy.

Prérequis

Gearboy avec serveur MCP — Construire à partir des sources
Une ROM de test simple — Utilisez une ROM de test homebrew ou les ROM de test de Blargg

Déroulement

Explorez la carte mémoire

Montre-moi la carte mémoire du Game Boy. Lisez l'en-tête de la ROM à 0x0100-0x014F et expliquez chaque champ.✓ Copié

→ En-tête annoté avec titre, type de cartouche, tailles ROM/RAM
Regardez la VRAM en action

Parcourez le gestionnaire d'interruption VBlank et expliquez comment les tuiles sont chargées dans la VRAM.✓ Copié

→ Explication étape par étape du chargement des tuiles avec l'état de la VRAM

Résultat : Compréhension pratique du matériel Game Boy grâce à l'exploration interactive.

Pièges

L'assemblage peut être écrasant pour les débutants — Commencez par de simples ROM de test qui exercent une fonctionnalité matérielle à la fois

Combinaisons

Associez-le à d'autres MCPs pour un effet X10

gearboy-2 + filesystem

Exportez les vidages de mémoire et les journaux de débogage pour une analyse hors ligne

Videz l'intégralité du contenu de la VRAM dans un fichier et annotez la disposition des données en mosaïque.✓ Copié

Outils

Ce que ce MCP expose

Outil	Entrées	Quand appeler
pause/resume/step	none / step_count?	Exécution de l’émulateur de contrôle
read_memory	address: int, size: int	Lire la mémoire de l'émulateur à n'importe quelle adresse
write_memory	address: int, data: bytes	Écrire dans la mémoire de l'émulateur
set_breakpoint	address: int, type?: str	Définir un point d'arrêt du processeur ou de la mémoire
disassemble	address: int, count: int	Instructions de démontage à une adresse
get_cpu_state	none	Obtenez les registres et indicateurs actuels du processeur

Coût et limites

Coût d'exécution

Quota d'API: N/A — entièrement local
Tokens par appel: 100–500 tokens per debug command
Monétaire: Free and open source (MIT license)
Astuce: Use targeted memory reads instead of full dumps to keep token usage low.

Sécurité

Permissions, secrets, portée

Stockage des identifiants : N/A

Sortie de données : Fully local — no network calls

Dépannage

Erreurs courantes et correctifs

MCP server not responding

Ensure Gearboy was built with MCP support enabled. Check that the server port (default 7777) is not in use.

Vérifier : 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.

Vérifier : 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.

Vérifier : Disassemble around the target address

Alternatives

Gearboy vs autres

Alternative	Quand l'utiliser	Compromis
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

Plus

Ressources

📖 Lire le README officiel sur GitHub

🐙 Voir les issues ouvertes

🔍 Parcourir les 400+ serveurs MCP et Skills