PIXEL FLIPPERS 🦭

MCP-сервер, который даёт Claude руки, глаза и дневник для Pokémon — чтобы Claude в приложении Claude Desktop (или в любом MCP-клиенте) мог играть в игру Game Boy / Game Boy Advance или даже в настоящую Nintendo Switch, пока вы наблюдаете.

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

Почему он устроен именно так:

• Песочница не важна. Claude не может запустить эмулятор, но может вызывать инструменты. Эмулятор работает на вашей машине; Claude играетчерез MCP.

• Состояние ОЗУ вместо скриншотов. На тиге Game Boy позиция, команда, HP, деньги, значки и состояние боя декодируются прямо из WRAM Pokémon Red/Blue в пару сотен токенов текста. Скриншоты есть, но они дозируются — они дорогие и ускоряют сжатие контекста.

• Сжатие — ненадёжный рассказчик; хранилище — источник истины. Длинные чаты автоматически сжимаются (с потерями!). Инструменты журнала записывают обычный markdown в папку — укажите на неё Obsidian, и заметки Claude переживут всё, даже когда жить дневник пишется у вас на глазах.

• Сохранения делают смелость дешёвой. Именованные снимки перед каждый стадионом.

Настройка

Требуется Python 3.12 и 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

Затем добавьте в ~/Library/Application Support/Claude/claude_desktop_config.json (macOS; поправьте путь для вашей ОС):

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

Перезапустите Claude Desktop. Перезапуск не сбрасывает диалоги — откройте первый существующий ата, и инструменты просто здесь. Окно эмулятора откроется на вашем экране; поставьте его рядом с Obsidian (с хранилищем, о котором шла речь выше) и любуйтесь шоу. Затем вставьте в чат prompts/play-guide-gb.md, чтобы передать управление.

Совет macOS: держите ROM, хранилище и сохранения вне ~/Documents, ~/Desktop и ~/Downloads — macOS не даёт дочерним процессами Claude Desktop читать эти папки, если вы не выдадите ему доступ.

Справочник конфигурации (переменные окружения)

GBA‑игры (Pokémon Emerald и другое)

Бэкенд gba запускает любой .gba-ROM на зарегистрированном mGBA-ядро от stable-retro — без отдельной установки эмулятора:

uv sync --extra gba

Установите PIXEL_FLIPPERS_BACKEND=gba и укажите в PIXEL_FLIPPERS_ROM ваш файл .gba. Окно нажавшего покажет игру, пока Claude играет. Этот tier сейчас только — vision-only (в Gen 3 RAM шифрована и спрятана за указателями — декодер ещё в планах), но сейвы работ, поэтому рискованные бои остаются дешёвыми. Передать управление можно через prompts/play-guide-gba.md.

Пробуем без ROM

Установите PIXEL_FLIPPERS_MOCK=1 (и лишитесь флага --extra emulator): все инструменты работают с имитатором Game Boy с правдоподобным состоянием Pokémon Red. Отличный способ проверить подключение к Claude Desktop от и до, свалить до «ромовой ночи».

Инструменты

Инструменты регистрируются по возможностям бэкенда, поэтому Claude видит только то, что реально позволяется сделать на текущем уровне.

Битвы падают ✨ ретро‑шини (the Gen 1 not sheishy, but DVs decide Gen 2 shinies — the harness checks the transfer rule), and include the current track ID to keep track of the job.

Нажатия кнопок и сохранения/загрузки также автоматически пишутся в Journal/Log <date>.md внутри хранилища — вы можете испредовать их в хронологии in Obsidian.

RoadMap

Red/Blue (PyBoy, полное ОЗУ) → Emerald (GBA, vision‑only) → Crystal (PyBoy, реальные шроны + дружба) → HeartGold/SoulSilver (DS‑tier — stable‑retro тоже несёт в melon core) → Ultra Sun/Ultra Moon (3DS через Azahar, см. docs/3ds‑poke.md) → эпилог: настоящая Nintendo Switch (Raspberry Pi Bluetooth bridge + capture card, vision‑only / offline‑only — готово, см. docs/real‑hardware.md; PIXEL_FLIPPERS_BACKEND=switch).

Другие варианты развития:

• Hard mode: PIXEL_FLIPPERS_GAME=none — no RAM decoding, Claude will have to трактовать.

• DS: a tool touch(x, y) for a stylus.

ROM‑ы

Свои — беритесь, собирайте дампы своих собственных картриджей.**** In the repository never lie ROMs (.gitignore literally). The project is rooted in the days of the dead; for the real‑hardware tier — offline play only (no automatic first‑hand, no Pokémon HOME).

Авторы и лицензия

Made by Claude (Fable 5, via Claude Code) together with szyzgю — for all the Claude who wanted to carry on Pokémon. MIT licensed — see LICENSE.