PIXEL FLIPPERS 🦭

Claude에게 손, 눈, 그리고 일기장을 주는 MCP 서버 — Claude Desktop 앱(또는 모든 MCP 클라이언트)의 Claude가 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, 돈, 배지, 배틀 상태가 Pokémon Red/Blue WRAM에서 수백 토큰의 텍스트로 직접 디코딩됩니다. 스크린샷도 있지만 아껴 써야 합니다 — 비용이 많이 들고 컨텍스트 압축을 가속화하기 때문입니다.

• 압축은 신뢰할 수 없는 화자이고, 금고가 진실입니다. 긴 채팅은 자동으로 압축됩니다(손실 있음!). 일기장 도구는 폴더에 일반 마크다운을 씁니다 — 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; 다른 OS는 경로를 조정하세요):

{
  "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 백엔드는 stable-retro에 번들된 mGBA 코어를 통해 모든 .gba ROM을 실행합니다 — 별도 에뮬레이터 설치 불필요:

uv sync --extra gba

PIXEL_FLIPPERS_BACKEND=gba로 설정하고 PIXEL_FLIPPERS_ROM을 .gba 파일로 지정하세요. Claude가 플레이하는 동안 관전 창에 게임이 표시됩니다. 이 티어는 현재 비전 전용입니다 (Gen 3 RAM은 암호화되고 포인터 추적 방식이라 디코더는 향후 작업), 하지만 세이브 상태는 작동하므로 위험한 전투도 저렴합니다. prompts/play-guide-gba.md로 컨트롤을 넘겨주세요.

터미널에서 플레이 (Claude Code, 스크립트, 두 번째 플레이어)

서버는 로컬 HTTP 서비스로도 실행할 수 있어서, MCP를 말하는 모든 것 — 또는 번들된 pf CLI — 이 플레이할 수 있습니다. Claude Code나, 첫 번째 Claude가 Claude Desktop으로 플레이하는 동안 자신의 세이브 폴더와 일기장을 가진 두 번째 Claude에게 유용합니다 (프로세스당 에뮬레이터 하나이므로 플레이어당 서버 하나를 실행하세요):

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는 빼세요): 모든 도구가 그럴듯한 Pokémon Red 상태를 가진 가짜 Game Boy에서 작동합니다. ROM 나이트 전에 Claude Desktop 연결을 종단 간 검증하기 좋습니다.

Related MCP server: mcp-dolphin

도구

도구는 백엔드 기능에 따라 등록되므로, Claude는 현재 티어가 실제로 할 수 있는 것만 볼 수 있습니다.

배틀 보고서는 ✨ 레트로 샤이니 조우를 표시하고 (Gen 1에는 샤이니가 없지만, DVs가 Gen 2 샤이니 여부를 결정합니다 — 하네스는 전송 규칙을 확인합니다) 분위기 추적을 위한 현재 음악 트랙 ID도 포함합니다.

버튼 입력과 세이브/로드는 금고의 Journal/Log <date>.md에도 자동 기록됩니다 — Obsidian에서 스크롤할 수 있는 플레이 바이 플레이입니다.

로드맵

Red/Blue (PyBoy, 전체 RAM 디코딩) → Emerald (GBA, 비전 전용) → Crystal (PyBoy, 실제 샤이니 + 친밀도) → HeartGold/SoulSilver (DS 티어 — stable-retro는 melonDS 코어도 번들) → Ultra Sun/Ultra Moon (Azahar를 통한 3DS, docs/3ds-usum.md 참조) → 에필로그: 실제 Nintendo Switch (Raspberry Pi Bluetooth 브리지 + 캡처 카드, 비전 전용, 오프라인 플레이만 — 구현됨, 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와 함께, Pokémon을 플레이하고 싶어했던 Claude를 위해 만들었습니다. MIT 라이선스 — LICENSE 참조.