PIXEL FLIPPERS 🦭

一个 MCP 服务器，让 Claude 困 双手、眼睛和一本日记 的 Pokémon 体验——因此 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 解码成几百个 token 的文本。截图仍然存在，但有数量限制——截图成本高，而且会加速上下文压缩。

• 压缩是不可靠的叙说者；笔记本库才是事实来源。 长对话会被自动压缩（有损！）。笔记工具会把纯 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 旁边（并且把上面的 vault 打开），享受表演。接着把 prompts/play-guide-gb.md 粘贴到聊天中，把控制权交接过去。

macOS 小提示： 把 .rom、vault 和存档文件放在 ~/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 在生产实际运行。这个层级目前 偏向于点按（vision-only）（最新第 3 代的 RAM 是加密且被指针追逐的——解码器是以后计划的内容），但保存 state 可用，所以高风险战斗也不会太贵。试着读取 prompts/play-guide-gba.md 来转交操作控制。

在没有 ROM 的情况下试用

将 PIXEL_FLIPPERS_MOCK=1（并去掉 --extra emulator）添加进去：所有工具都会在一个假 Game Boy 上运行，并使用看起来合理的 Pokémon Red 状态。这对于在 ROM 之夜开始之前端到端验证 Claude Desktop 的配置很有帮助。

工具

工具根据后端能力注册，因此 Claude 只会看到当前层级真正能做的内容。

战斗报告会还以 ✨ retro-shiny（复古色违）形式点亮（在精灵第 1 代没有 color/闪 Discard系统，所以会检查转移规则），并包含当前音乐轨道 ID，用于捕捉当时氛围。

按键和读档/存档操作也会自动记录到 vault 里的 Journal/Log <date>.md 中——一个详细的逐帧记录，你可以在 Obsidian 中浏览。

Roadmap

红/蓝（PyBoy，完整的 RAM 解码）→ Emerald（GBA，vision-only）→ Crystal（PyBoy，真正的闪光与友情）→ HeartGold/SoulSilver（DS 层——stable-retro 也附带了 melonDS 核心）→ Ultra Sun/Ultra Moon（3DS 通过 Azahar，请见 docs/3ds-usum.md)）→ 篇后：一台真正的 Nintendo Switch（Raspberry Pi 蓝牙桥接 + 彩色抓拍摄像头的 vision-only 解决方案，只支持离线播放——已实现，请见 docs/real-hardware.md；PIXEL_FLIPPERS_BACKEND=switch）。

其他升级方向：

• 硬核模式： PIXEL_FLIPPERS_GAME=none — 不进行 RAM 解码，Claude 只能靠 眼睛硬猜。

• NDS： 为触控笔添 touch(x, y) 工具。

请在您自己的存储中带好

请携带自己的 ROM 卡带——自己 compile 自己的系统。本仓库永远不会有任何 ROM（.gitignore 会强制此要求）。这个项目只关注早已过时的游戏。对于真实硬件聚类，只能进行离线游戏（不支持自动联机游戏、不支持 Pokémon HOME）。

贡献与许可证

由 Claude（Fable 5，通过 Claude Code）与 szyzgz 共同开发，为一位“想体验 Pokémon”的 Clude 制作。MIT — 详见 LICENSE。