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.

• Состояние RAM вместо скриншотов. На уровне 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 играет. Этот уровень пока только визуальный (RAM поколения 3 зашифрована и требует отслеживания указателей — декодер будет в будущем), но сохранения работают, так что рискованные бои остаются дешёвыми. Передайте управление с помощью prompts/play-guide-gba.md.

Игра из терминала (Claude Code, скрипты, второй игрок)

Сервер также может работать как локальный HTTP-сервис, так что всё, что говорит на MCP — или встроенный CLI pf — может играть. Удобно для Claude Code или для второго Claude со своей папкой сохранений и дневником, пока первый играет через Claude Desktop (один эмулятор на процесс, поэтому запускайте один сервер на игрока):

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 помещает имя в заголовок окна зрителя, чтобы два окна рядом можно было различить. HTTP-сервер привязывается только к 127.0.0.1.

Попробовать без ROM

Установите PIXEL_FLIPPERS_MOCK=1 (и уберите --extra emulator): все инструменты работают с фейковым Game Boy с правдоподобным состоянием Pokémon Red. Полезно для проверки соединения с Claude Desktop от начала до конца перед вечером с ROM.

Related MCP server: mcp-dolphin

Инструменты

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

Боевые отчёты помечают ✨ ретро-блестящие встречи (в Gen 1 нет блестящих, но DVs определяют блеск в Gen 2 — проверяется правило переноса) и включают идентификатор текущей музыкальной дорожки для отслеживания атмосферы.

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

Дорожная карта

Red/Blue (PyBoy, полное декодирование RAM) → Emerald (GBA, только визуально) → Crystal (PyBoy, настоящие блестящие + дружба) → HeartGold/SoulSilver (уровень DS — stable-retro также включает ядро melonDS) → Ultra Sun/Ultra Moon (3DS через Azahar, см. docs/3ds-usum.md) → эпилог: настоящая Nintendo Switch (мост Bluetooth на Raspberry Pi + карта захвата, только визуально, только офлайн — реализовано, см. docs/real-hardware.md; PIXEL_FLIPPERS_BACKEND=switch).

Другие идеи для усложнения:

• Сложный режим: PIXEL_FLIPPERS_GAME=none — без декодирования RAM, Claude должен видеть.

• DS: инструмент touch(x, y) для стилуса.

ROM

Приносите свои — дампите свои картриджи. В этом репозитории никогда не будет ROM (это обеспечивает .gitignore). Проект придерживается игр, давно снятых с производства; для уровня реального железа — только офлайн-игра (без автоматической онлайн-игры, без Pokémon HOME).

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

Создано Claude (Fable 5, через Claude Code) вместе с szyzgz, для Claude, который хотел играть в Pokémon. Лицензия MIT — см. LICENSE.