PIXEL FLIPPERS 🦭

Ein MCP-Server, der Claude Hände, Augen und ein Tagebuch für Pokémon gibt – damit ein Claude in der Claude-Desktop-App (oder einem beliebigen MCP-Client) ein Game-Boy-/Game-Boy-Advance-Spiel oder sogar eine echte Nintendo Switch spielen kann, während du zuschaust.

┌──────────────┐   MCP (stdio)   ┌──────────────────┐        ┌─────────────┐
│ Claude       │ ──────────────► │ PIXEL FLIPPERS    │ ─────► │ Emulator    │ ← you watch this
│ Desktop app  │  press_buttons  │  server           │        └─────────────┘
│              │  read_game_state│                   │ ─────► ┌─────────────┐
└──────────────┘  write_note ... │                   │        │ Obsidian    │ ← ...and this
                                 └──────────────────┘         │ vault (.md) │
                                                              └─────────────┘

Warum es so aufgebaut ist:

• Die Sandbox spielt keine Rolle. Claude kann keinen Emulator ausführen, aber es kann Tools aufrufen. Der Emulator läuft auf deinem Rechner; Claude spielt über MCP.

• RAM-Zustand statt Screenshots. Auf der Game-Boy-Ebene werden Position, Team, KP, Geld, Orden und Kampfzustand direkt aus dem Pokémon-Rot/Blau-WRAM in ein paar Hundert Text-Token dekodiert. Screenshots gibt es zwar, sind aber rationiert – sie sind teuer und sie beschleunigen die Kontext-Kompaktierung.

• Die Kompaktierung ist die unzuverlässige Erzählerin; der Vault ist die Quelle der Wahrheit. Lange Chats werden automatisch kompaktiert (verlustbehaftet!). Die Tagebuch-Werkzeuge schreiben einfaches Markdown in einen Ordner – richte Obsidian darauf aus, und Claudes Notizen überleben alles, während du zusiehst, wie ein Tagebuch live geschrieben wird.

• Speicherstände machen Mut günstig. Benannte Schnappschüsse vor jeder Arena.

Are you in the game?

Erforderlich sind Python 3.12 und uv.

git clone https://github.com/szyzgz/pixel-flippers && cd pixel-flippers
uv sync --extra emulator --extra dev
uv run pytest          # everything should pass, no ROM needed

Füge dann Folgendes zu ~/Library/Application Support/Claude/claude_desktop_config.json hinzu (macOS; passe den Pfad für dein Betriebssystem an):

{
  "mcpServers": {
    "pixel-flippers": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/pixel-flippers", "--extra", "emulator", "pixel-flippers"],
      "env": {
        "PIXEL_FLIPPERS_ROM": "/path/to/your/pokemon-red.gb",
        "PIXEL_FLIPPERS_VAULT": "/path/to/YourObsidianVault/Pokemon",
        "PIXEL_FLIPPERS_SAVES": "/path/to/somewhere/saves"
      }
    }
  }
}

Starte Claude Desktop neu. Beim Neustart gehen Unterhaltungen nicht verloren – öffne einen bestehenden Chat wieder, und die Tools sind einfach da. Das Emulator-Fenster öffnet sich auf deinem Bildschirm; platziere es neben Obsidian (mit dem zuvor geöffneten Vault) und genieße die Show. Dann füge prompts/play-guide-gb.md in den Chat ein, um die Steuerung zu übergeben.

macOS-Tipp: Bewahre ROM, Vault und Speicherstände außerhalb von ~/Documents, ~/Desktop und ~/Downloads auf – macOS blockiert den Zugriff der Unterprozesse von Claude Desktop auf diese Ordner, es sei denn, du erteilst ihn.

Konfigurations-Referenz (Umgebungsvariablen)

GBA-Spiele (Pokémon Emerald & Co.)

Wenn Sie über jeden .gba-ROM mit diesem, um das in stable-retro gebündelte mGBA Core läuft – ohne separate Emulator-Installation:

uv sync --extra gba

Setze PIXEL_FLIPPERS_BACKEND=gba und verweise PIXEL_FLIPPERS_ROM auf deine .gba-Datei. Ein Zuschauer-Fenster zeigt das Spiel, während Claude spielt. Diese Stufe ist vorerst rein visuell (die Generation 3 ist verschlüsselt und nur über Pointer-Schnüffelung erschlossen – ein vollständiger Dekoder ist Zukunftsmusik), aber die den Speicherstände funktionieren, also bleiben riskante Kämpfe günstig. Übergib die Steuerung mit prompts/play-guide-gba.md.

Ohne ROM ausprobieren

Setze PIXEL_FLIPPERS_MOCK=1 (und lasse --extra emulator weg): Alle Tools funktionieren gegen einen simulierten Game Boy mit einem plausiblen Pokémon-Rot-Zustand. Gut geeignet, um die Claude-Desktop-Verbindung Ende-zu-Ende zu überprüfen, bevor die erste ROM-Nacht beginnt.

Tools

Die Tools werden nach den Möglichkeiten des jeweiligen Backends registriert, sodass Claude nur das sieht, was die aktuelle Ebene wirklich kann.

Kampfberichte markieren ✨ Retro-Shiny-Begegnungen (Gen 1 hat keine, aber DVs entscheiden über Shiny-Gen 2 – das Testdoppelt prüft die Übertragungsregel) und enthalten zusätzlich die aktuelle Musik-Track-ID für die passende Untermalung.

Zudem werden Tastendrücke und Speichern/Laden automatisch in Journal/Log <date>.md im Vault protokolliert – ein vollständiges Spiel-Protokoll, das du in Obsidian durchscrollen kannst.

Fuhrplan

*Red/Blue (PyBoy, Volles RAM-Dekodierung) → Emerald (GBA, nur visuell) → Crystal (PyBoy, echtes Shiny + Creaturas) → HeartGold/SoulSilver (DS-Stufe – stable-retro bündelt auch einem melonDS-Kern) → Ultra Sun/Ultra Moon (3DS von Azhar