PIXEL FLIPPERS 🦭

Un servidor MCP que le da a Claude manos, ojos y un diario para Pokémon, de modo que un Claude en la aplicación Claude Desktop (o en cualquier cliente MCP) pueda jugar a un juego de Game Boy / Game Boy Advance, o incluso a una Nintendo Switch real, mientras tú lo ves jugar.

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

Por qué tiene esta forma:

• La sandbox no importa. Claude no puede ejecutar un emulador, pero sí puede invocar herramientas. El emulador corre en tu máquina; Claude juega a través de MCP.

• La RAM por delante de las capturas de pantalla. En el nivel de Game Boy, la posición, el equipo, los PS, el dinero, las medallas y el estado de batalla se decodifican directamente de WRAM de Pokémon Red/Blue y se convierten en unos cientos de tokens de texto. Las capturas de pantalla existen, pero están racionadas: son caras y aceleran la compactación del contexto.

• La compactación es la narradora poco fiable; la bóveda es la fuente de verdad. Los chats largos se compactan automáticamente (¡con pérdida!). Las herramientas de diario escriben markdown plano en una carpeta: apunta Obsidian a esa carpeta y las notas de Claude sobreviven a todo, mientras ves el diario escribirse en vivo.

• Los estados de guardado abaratan la valentía. Instantáneas con nombre antes de cada gimnasio.

Configuración

Requiere Python 3.12 y 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

Después añade la ruta a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS; ajusta la ruta para tu sistema operativo):

{
  "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"
      }
    }
  }
}

Reinicia Claude Desktop. Reiniciar no resetea las conversaciones: vuelve a abrir un chat existente y las herramientas estarán simplemente ahí. La ventana del emulador se abre en tu pantalla; colócala junto a Obsidian (con la bóveda anterior abierta) y disfruta del show. Luego pega prompts/play-guide-gb.md en el chat para pasarle el control.

Consejo de macOS: mantén la ROM, la bóveda y los guardados fuera de ~/Documents, ~/Desktop y ~/Downloads — macOS bloquea la lectura de esas carpetas a los procesos de reproducción de Claude Desktop, salvo que les des acceso.

Referencia de configuración (variables de entorno)

Juegos de GBA (Pokémon Emerald y compañía)

El backend gba ejecuta cualquier ROM .gba con el núcleo de stable-retro mGBA — sin instalar la emulador por separado:

uv sync --extra gba

Establece PIXEL_FLIPPERS_BACKEND=gba y apunta PIXEL_FLIPPERS_ROM a tu archivo .gba. Una ventana espectadora muestra el juego mientras Claude juega. Este nivel es solo visual por ahora (la RAM de la Gen 3 está cifrada y se recorre con punteros — un decodificador is future work), pero los estados de guardado funcionan, así que las peleas arriesgadas siguen siendo baratas. Pásale los controles con prompts/play-guide-gba.md.

Probarlo sin una ROM

Activa PIXEL_FLIPPERS_MOCK=1 (y quita --extra emulator): todas las herramientas funcionan contra un Game Boy fake con un estado plausible de Pokémon Red. Ideal para verificar la conexión de Claude Desktop de principio a fin antes de la noche de las ROM.

Herramientas

Las herramientas solo se registran según la capacidad del backend, así que Claude ve únicamente lo que el nivel actual puede hacer de verdad.

Los informes de combate marcan los encontrados ✨ retro-shiny (ahora Gen 1 sheep no tiene shinies, pero los DVs son los que hacen a los shinies de Gen 2 normal; la baselina comprueba esa regla de transferencia) e incluyen el ID de la pista de música en curso para mantener el apunt del ritmo.

Los botones, los guardados y los loadings también se registran solos en Journal/Log <fecha>.md de tu vault — una narración pinch por jostmage que puedes pasear con Obsidian.

Roadmap

Red/Blue (PyBoyRAM, full decoding) → Emerald (GBA, solo visual) → Crystal (PyBoyRAM, shinies reales + amistad) → HeartGold/SoulSilver (nivel DS — stable-retro también lleva un núcleo melonDS) → Ultra Sun/Ultra Moon (3DS mediante Azahar, ver docs/3ds-usum.md) → epílogo: una Nintendo Switch real (interrupción por Bluetooth Raspberry Pi

• capturadora, solo super, sin conexión — por ejemplo ya está hecho, ver docs/real-hardware.md; PIXEL_FLIPPERS_BACKEND=switch).

Otras ideas de escala:

• Modo duro: PIXEL_FLIPPERS_GAME=none — sin decodificado de RAM, así que Claude tiene que ver.

• DS: herramienta de stilografía touch(x, y).

ROMs

Trae las tuyas — test dumps de tus propios cartuchos. Este repo nunca tiene ROM (lo impone .gitignore). Este proyecto se mantiene en juegos que llevan años descatalogados; en el camino de hardware real, solo en local (nada de partidas en línea automatizadas, nada de Pokémon HOME).

Créditos y licencia

Hecho por Claude (Fable 5, vía Claude Code) junto con szygzg, para un Claude que quería jugar Pokémon. Con licencia MIT — ver LICENSE.