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 기준, 운영 체제에 따라 경로 조정):

{
  "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의 자식 프로세스들이 그 폴더를 읽지 못하게 막아놓았기 때문입니다.

구성 reluk (환경 변수)

GBA 게임 (포켓몬 Emerald와 같은)

gba 백엔드는 stable-retro에 번들된 mGBA 코어를 통해 모든 .gba ROM을 실행합니다 — 별도의 에뮬레이터 설치가 필요 없습니다:

uv sync --extra gba

PIXEL_FLIPPERS_BACKEND=gba로 설정하고 PIXEL_FLIPPERS_ROM이 .gba 파일을 가리키게 하면 됩니다. Claude가 게임을 할 때 스펙터 글창에서 화면을 볼 수 있습니다. 이 티어는 지금은 시각만 사용입니다. (3세대 RAM은 암호화되어 있고 포인터 추적도 해야 해서 디코더는 다음 작업으로 미뤘습니다.) 다만 세이브 상태는 되기 있으니, 힘든 전투도 부담 없이 할 수 있습니다. prompts/play-guide-gba.md를 붙여넣어 조종권을 넘겨주세요.

ROM 없이 시작해 보기

PIXEL_FLIPPERS_MOCK =1 (그리고 --extra emulator 스파이핑)로 설정하면: 그럴듯한 파이일 + 실제 같은 상태의 가짜 Game Boy를 대상으로 모든 도구가 동작합니다. ROM 실행 전 워밍업으로 Claude Desktop을 엔드투엔드 확인하기에 좋습니다.

도구

도구는 백엔드 능력에 따라서만 등록되므로 Claude는 현 티어에서 실제로 못 할 기능은 아예 표시되지 않습니다.

배틀 리포트는 ✨레트로 셔니 발견을 표시한다 (1세대에는 셔니가 없지만, 극악/0은 2세대 셔니를 결정하니, 하니스가 재료 규칙을 확인한다) 그 누구나 현재 상황 트랙 ID도 포함하여 을 분위기를 추적하게 해 준다.

버튼 조작과 세이브/로드도 저장소의 Journal/Log <data>.md 파일에도 자동으로 기록된다 — Obsidian에서 스크롤해 보던のは즉 실황 기록입니다.

계획 (Roadmap)

레드/블루(PyBoy ・ RAM 완전 데객) → 에메랄드 (GBA, 보기 전용) → 크리스탈 (PyBoy, 급정 못이름+친밀도) → HeartGold/SoulSilver (DS 티어 — stable-retro는 melonDS 때일도 포함) → 울트라썬/울트라문 (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: 스타일러스용 uhr을 (x, y) 터치 도구.

ROM (롬)

직접 챙기세요 / Separate — 자신이 가진 패드를 덤프하세요. 이 리포지토리에는 ROM을 가져던 않고 `(.gitignore가 지킨 대로 어떤 ROM도 결班 넣지 못۸). 이 프로젝트는 오래전 판이 절판인 게임만 다루며, 실물 하로드 티어는 오프라인 플레이만 (자동 온라인 진행 없음, Pokémon HOME 배제).

만든 사람

포켓몬을 플레이하길 원했던 Claude로 인해, Claude (Fable 5, via Claude Code)과 szyzgz가 함께 만들었습니다. MIT 라이선스로 배포됩니다 — LICENSE 참조.