PIXEL FLIPPERS 🦭

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

┌──────────────┐   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?

• El sandbox no importa. Claude no puede ejecutar un emulador, pero puede llamar a herramientas. El emulador se ejecuta en tu máquina; Claude juega a través de MCP.

• El estado de la RAM por encima 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 la WRAM de Pokémon Red/Blue a unos pocos 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 el narrador poco fiable; la bóveda es la verdad absoluta. Las conversaciones largas se compactan automáticamente (¡con pérdida!). Las herramientas de diario escriben markdown plano en una carpeta: apunta Obsidian a ella y las notas de Claude sobreviven a todo, mientras ves cómo se escribe el diario en vivo.

• Los estados de guardado hacen que el valor sea barato. 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

Luego añade 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 restablece las conversaciones: vuelve a abrir un chat existente y las herramientas simplemente están ahí. La ventana del emulador se abre en tu pantalla; ponla junto a Obsidian (con la bóveda abierta) y disfruta del espectáculo. Luego pega prompts/play-guide-gb.md en el chat para entregar los controles.

Consejo para macOS: mantén la ROM, la bóveda y los guardados fuera de ~/Documents, ~/Desktop y ~/Downloads — macOS bloquea a los procesos hijos de Claude Desktop para que no lean esas carpetas a menos que le concedas acceso.

Referencia de configuración (variables de entorno)

Juegos de GBA (Pokémon Emerald y amigos)

El backend gba ejecuta cualquier ROM .gba a través del núcleo mGBA incluido en stable-retro — sin necesidad de instalar un emulador aparte:

uv sync --extra gba

Establece PIXEL_FLIPPERS_BACKEND=gba y apunta PIXEL_FLIPPERS_ROM a tu archivo .gba. Una ventana de espectador muestra el juego mientras Claude juega. Este nivel es solo visión por ahora (la RAM de la Gen 3 está cifrada y con punteros — un decodificador es trabajo futuro), pero los estados de guardado funcionan, así que las peleas arriesgadas siguen siendo baratas. Entrega los controles con prompts/play-guide-gba.md.

Jugar desde una terminal (Claude Code, scripts, un segundo jugador)

El servidor también puede ejecutarse como un servicio HTTP local, para que cualquier cosa que hable MCP — o el CLI pf incluido — pueda jugar. Útil para Claude Code, o para un segundo Claude con su propia carpeta de guardado y diario mientras el primero juega a través de Claude Desktop (un emulador por proceso, así que ejecuta un servidor por jugador):

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 pone el nombre en el título de la ventana del espectador para que dos ventanas una al lado de la otra se puedan distinguir. El servidor HTTP se vincula solo a 127.0.0.1.

Probarlo sin una ROM

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

Related MCP server: mcp-dolphin

Herramientas

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

Los informes de batalla marcan ✨ encuentros retro-shiny (la Gen 1 no tiene shinies, pero los DVs deciden el shiny de la Gen 2 — el arnés comprueba la regla de transferencia) e incluyen el ID de la pista de música actual para seguir el ambiente.

Los pulsos de botones y las cargas/guardados también se registran automáticamente en Journal/Log <fecha>.md en la bóveda — una jugada a jugada que puedes desplazarte en Obsidian.

Hoja de ruta

Red/Blue (PyBoy, decodificación completa de RAM) → Emerald (GBA, solo visión) → Crystal (PyBoy, shinies reales + amistad) → HeartGold/SoulSilver (nivel DS — stable-retro también incluye un núcleo melonDS) → Ultra Sun/Ultra Moon (3DS vía Azahar, ver docs/3ds-usum.md) → epílogo: una Nintendo Switch real (puente Bluetooth con Raspberry Pi + tarjeta de captura, solo visión, solo juego sin conexión — implementado, ver docs/real-hardware.md; PIXEL_FLIPPERS_BACKEND=switch).

Otras ideas de escalada:

• Modo difícil: PIXEL_FLIPPERS_GAME=none — sin decodificación de RAM, Claude tiene que ver.

• DS: una herramienta touch(x, y) para el lápiz.

ROMs

Trae las tuyas — haz volcados de tus propios cartuchos. No hay ROMs en este repositorio, nunca (.gitignore lo impone). Este proyecto se limita a juegos descatalogados desde hace tiempo; para el nivel de hardware real, solo juego sin conexión (sin juego en línea automatizado, sin Pokémon HOME).

Créditos y licencia

Construido por Claude (Fable 5, vía Claude Code) junto con szyzgz, para un Claude que quería jugar a Pokémon. Licencia MIT — ver LICENSE.