mcp-mgba 是一个基于 Model Context Protocol（MCP）的服务器，旨在将 Claude（及其他 MCP 兼容客户端）与 mGBA Game Boy Advance 模拟器连接起来。
使用方式： 该工具通过 Lua 脚本桥接实现功能。mGBA 的脚本引擎内运行 lua/bridge.lua，它会在本地回环地址上开启 TCP 服务器（端口 8765）。Node.js 编写的 MCP 服务器（dist/index.js）通过 TCP 与 Lua 桥接通信，并以 stdio 方式对外暴露工具。
主要能力：
- 读取和写入 GBA 内存
- 注入按钮按下（支持的按键包括 A、B、Select、Start、Right、Left、Up、Down、R、L）
- 截取屏幕截图
- 单步执行模拟器
前置要求：
- mGBA 0.10 或更新版本（需支持 Lua 脚本）
- Node.js 22+（用于 MCP 服务器）
安装方式： 方式 A —— 从 npm 安装（推荐）：全局安装后 mcp-mgba 会加入 PATH。 方式 B —— 使用 npx（无需安装）：按需运行，适合试用。 方式 C —— 克隆仓库并开发：在注册时引用 dist/index.js 的绝对路径，或使用 npm install -g . 全局链接。
设置 mGBA 桥接：
- 启动 mGBA 并加载任意 GBA ROM。
- 打开 Tools > Scripting…。
- 点击 File > Load script，选择本仓库中的 lua/bridge.lua。 若出现 bind failed 错误，说明上一个实例的套接字仍被占用，需退出并重新启动 mGBA。
注册 MCP 客户端：
- Claude Code (CLI)：若使用方式 B 且未全局安装，将 mcp-mgba 替换为 node /absolute/path/to/dist/index.js。
- Claude Desktop：编辑 claude_desktop_config.json 并添加相应配置，重启 Claude Desktop 后生效。
- 其他 MCP 客户端：该服务器通过 stdio 使用标准 MCP 协议，运行 mcp-mgba（或 node dist/index.js），让任何 MCP 客户端连接其 stdio 即可。
更多示例可参考 docs/RECIPES.md，其中包含 RAM 搜索、快照-实验-恢复、横版卷轴游戏自动化等端到端案例。
调试与开发：
- Lua 端（lua/bridge.lua 和 lua/json.lua）无需构建步骤，编辑后通过 mGBA 的 File > Load script 重新加载。
- 可使用 MCP Inspector 交互式浏览和调用工具。若修改过 src/，需先构建（npm run build）或保持 npm run dev 运行。可通过 MGBA_HOST / MGBA_PORT 覆盖桥接地址（默认 127.0.0.1:8765）。即使未连接 mGBA，tools/list 也可工作；调用工具则需要 mGBA 打开并加载 lua/bridge.lua。
适用场景： 适用于希望通过 AI 模型自动化控制 GBA 模拟器的开发者、研究人员或爱好者，例如自动化测试、游戏 AI 实验、内存分析等。
限制： 需明确 mGBA 0.10+ 和 Node.js 22+ 环境；Lua 桥接需手动在 mGBA 中加载脚本；端口占用可能导致冲突需重启模拟器。其他具体限制暂未提供。