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がプレイします。このティアは現時点ではビジョンのみです（第3世代のRAMは暗号化され、ポインタ追跡が必要です。デコーダは将来の作業です）。ただしセーブステートは機能するので、危険な戦闘も安上がりです。prompts/play-guide-gba.mdでコントロールを引き渡します。

ターミナルからプレイ（Claude Code、スクリプト、2人目のプレイヤー）

サーバーはローカルHTTPサービスとしても実行できるため、MCPを話すものなら何でも（または同梱のpf CLI）プレイできます。Claude Codeや、最初のClaudeがClaude Desktopでプレイしている間に、独自のセーブフォルダと日記を持つ2人目のClaudeに便利です（プロセスごとに1つのエミュレータなので、プレイヤーごとに1つのサーバーを実行してください）：

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は、観客ウィンドウのタイトルに名前を表示するため、2つのウィンドウを並べても区別できます。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は現在のティアが実際にできることだけを見ることができます。

バトルレポートは✨レトロ色違いの遭遇をフラグ付けします（第1世代には色違いはありませんが、DVが第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とともに、ポケモンをプレイしたいと思ったClaudeのために構築しました。MITライセンス — LICENSEを参照してください。