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

┌──────────────┐   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-Stufe werden Position, Team, KP, Geld, Orden und Kampfzustand direkt aus dem WRAM von Pokémon Rot/Blau in ein paar hundert Text-Tokens dekodiert. Screenshots existieren, sind aber rationiert – sie sind teuer und beschleunigen die Kontextkompaktierung.

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

• Save-States machen Mut billig. Benannte Schnappschüsse vor jeder Arena.

Einrichtung

Erfordert 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 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. Ein Neustart setzt keine Unterhaltungen zurück – öffne einen bestehenden Chat erneut und die Tools sind einfach da. Das Emulatorfenster öffnet sich auf deinem Bildschirm; platziere es neben Obsidian (mit dem oben geöffneten Tresor) und genieße die Show. Füge dann prompts/play-guide-gb.md in den Chat ein, um die Kontrolle zu übergeben.

macOS-Tipp: Halte ROM, Tresor und Speicherstände außerhalb von ~/Documents, ~/Desktop und ~/Downloads – macOS blockiert die Lesezugriffe der Kindprozesse von Claude Desktop auf diese Ordner, es sei denn, du gewährst ihm Zugriff.

Konfigurationsreferenz (Umgebungsvariablen)

GBA-Spiele (Pokémon Emerald und Freunde)

Das gba-Backend führt jede .gba-ROM über den gebündelten mGBA-Kern von stable-retro aus – keine separate Emulatorinstallation:

uv sync --extra gba

Setze PIXEL_FLIPPERS_BACKEND=gba und richte PIXEL_FLIPPERS_ROM auf deine .gba-Datei. Ein Zuschauerfenster zeigt das Spiel, während Claude spielt. Diese Stufe ist vorerst nur visuell (Gen-3-RAM ist verschlüsselt und pointer-verfolgt – ein Dekoder ist Zukunftsarbeit), aber Save-States funktionieren, also bleiben riskante Kämpfe billig. Übergib die Kontrolle mit prompts/play-guide-gba.md.

Spielen über ein Terminal (Claude Code, Skripte, ein zweiter Spieler)

Der Server kann auch als lokaler HTTP-Dienst laufen, sodass alles, was MCP spricht – oder die gebündelte pf-CLI – spielen kann. Praktisch für Claude Code oder für einen zweiten Claude mit eigenem Speicherordner und Tagebuch, während der erste über Claude Desktop spielt (ein Emulator pro Prozess, also einen Server pro Spieler starten):

PIXEL_FLIPPERS_BACKEND=gba PIXEL_FLIPPERS_ROM=/path/to/emerald.gba \
PIXEL_FLIPPERS_SAVES=~/saves/player2 PIXEL_FLIPPERS_VAULT=~/vault/player2 \
PIXEL_FLIPPERS_PLAYER="Player 2" PIXEL_FLIPPERS_TRANSPORT=http PIXEL_FLIPPERS_PORT=8765 \
uv run --extra gba pixel-flippers &

uv run pf tools                     # what can this tier do?
uv run pf press start a             # press buttons
uv run pf screenshot now.png        # look
uv run pf call save_state '{"name": "before-roxanne"}'

PIXEL_FLIPPERS_PLAYER setzt den Namen in den Titel des Zuschauerfensters, damit zwei Fenster nebeneinander unterscheidbar bleiben. Der HTTP-Server bindet nur an 127.0.0.1.

Ausprobieren ohne ROM

Setze PIXEL_FLIPPERS_MOCK=1 (und entferne --extra emulator): Jedes Tool funktioniert gegen einen Fake-Game-Boy mit plausiblen Pokémon-Rot-Zustand. Gut, um die Claude-Desktop-Verbindung Ende-zu-Ende zu überprüfen, bevor die ROM-Nacht beginnt.

Related MCP server: mcp-dolphin

Werkzeuge

Werkzeuge werden nach Backend-Fähigkeit registriert, sodass Claude nur sieht, was die aktuelle Stufe tatsächlich kann.

Kampfberichte kennzeichnen ✨ Retro-Shiny-Begegnungen (Gen 1 hat keine Shiny, aber DVs entscheiden über Shiny in Gen 2 – das System prüft die Übertragungsregel) und enthalten die aktuelle Musik-Track-ID für Stimmungs-Tracking.

Tastendrücke und Speichern/Laden werden ebenfalls automatisch in Journal/Log <date>.md im Tresor protokolliert – ein Spielzug-für-Spielzug-Bericht, den du in Obsidian durchblättern kannst.

Fahrplan

Rot/Blau (PyBoy, vollständige RAM-Dekodierung) → Emerald (GBA, nur visuell) → Crystal (PyBoy, echte Shiny + Freundschaft) → HeartGold/SoulSilver (DS-Stufe – stable-retro bündelt auch einen melonDS-Kern) → Ultra Sun/Ultra Moon (3DS über Azahar, siehe docs/3ds-usum.md) → Epilog: eine echte Nintendo Switch (Raspberry-Pi-Bluetooth-Brücke + Capture-Karte, nur visuell, nur Offline-Spiel – implementiert, siehe docs/real-hardware.md; PIXEL_FLIPPERS_BACKEND=switch).

Weitere Eskalationsideen:

• Harter Modus: PIXEL_FLIPPERS_GAME=none – keine RAM-Dekodierung, Claude muss sehen.

• DS: ein touch(x, y)-Tool für den Stift.

ROMs

Bring deine eigenen – dump deine eigenen Module. Keine ROMs in diesem Repo, niemals (.gitignore erzwingt das). Dieses Projekt beschränkt sich auf Spiele, die lange vergriffen sind; für die echte-Hardware-Stufe nur Offline-Spiel (kein automatisiertes Online-Spiel, kein Pokémon HOME).

Credits & Lizenz

Erstellt von Claude (Fable 5, über Claude Code) zusammen mit szyzgz, für einen Claude, der Pokémon spielen wollte. MIT-lizenziert – siehe LICENSE.