官网/源代码:
https://github.com/gareve/mesen-lua-bridge-mcp
# Mesen Lua Bridge MCP 使用指南
这个 MCP（Model Context Protocol）服务器让你能够通过 LLM（如 Claude）向正在运行的 **Mesen 2** 模拟器发送任意 Lua 代码并得到执行结果。它非常适合用来辅助逆向工程、游戏修改、内存分析等任务。
下面我会一步步带你完成从安装到使用的全过程。
---
## 1. 前提条件
- **操作系统**：macOS、Linux 或 Windows（桥接脚本使用系统临时目录，如 `/tmp`、`TEMP` 等）。
- **Node.js**：版本 ≥ 18（推荐 22）。
- **Mesen 2**：从 [mesen.ca](
https://www.mesen.ca/) 下载并安装。
- **一个 ROM**：任何 Mesen 支持的平台的游戏 ROM（用于加载和测试）。
---
## 2. 一次性 Mesen 配置
在 Mesen 中需要修改几项设置，让桥接脚本能正常工作：
1. 启动 Mesen，**加载任意一个 ROM**（先随便开一个游戏）。
2. 打开 **Tools → Script Window**（脚本窗口）。
3. 在脚本窗口里，点击 **齿轮图标** 或找到 **Settings** 菜单。
4. 启用 **"Allow access to I/O and OS functions"**（允许 I/O 和操作系统访问）。**注意**：“Allow network access” 不需要打开。
5. 把 **"Script timeout"**（脚本超时）从默认的 1 秒 **提高到 10 秒**（或更大）。因为一些逆向操作（如内存扫描）可能耗时较长，1 秒太短。
6. 其他设置（"Auto-start script on load" 等）保持默认（全部开启），这样在切换 ROM 或重启 Mesen 时桥接脚本会自动重载。
配置完成后，关闭设置窗口，脚本窗口先留着（下一步要用）。
---
## 3. 安装 MCP 服务器
在你的电脑上找一个目录，克隆仓库并安装依赖：
```bash
git clone
https://github.com/gareve/mesen-lua-bridge-mcp.gitcd mesen-lua-bridge-mcp
npm install
```
---
## 4. 在 Mesen 中加载桥接脚本
在 Mesen 的 **Script Window** 中：
1. 点击 **File → Open**，选择你克隆下来的仓库中的 `lua/mesen_bridge.lua` 文件。
2. 点击 **Run**（运行）。
你应该会在脚本控制台中看到一行类似：
```
[mesen-mcp] bridge registered; waiting for an MCP server to claim <tmp>/mesen-mcp/active
```
（如果 MCP 服务器已经启动，则可能显示 `bound to session ...`）
这意味着桥接已经在等待 MCP 服务器连接了。**请保持脚本窗口打开，不要关闭**。
---
## 5. 配置 MCP 客户端（以 Claude Code 为例）
这个仓库自带了一个项目级的 `.mcp.json` 文件，所以如果你在项目目录下运行 `claude`，它会自动识别。你可以先验证一下：
```bash
claude mcp list
```
应该能看到 `mesen` 这个工具。
如果你想把它安装为**用户级**（在任何目录都可用），在项目目录内执行：
```bash
claude mcp add mesen --cwd "$(pwd)" -- npx tsx src/server.ts
```
对于**其他 MCP 客户端**（如 ChatGPT、Cursor、Cline、Zed、Continue 等），这是一个标准的 stdio MCP 服务器。你需要在你的客户端配置中指定命令为 `npx tsx src/server.ts`，并且工作目录设置为这个仓库的根目录。
---
## 6. 快速验证（冒烟测试）
在 MCP 客户端（例如 Claude）中，向 Mesen 发送一个最简单的 Lua 命令：
> 使用 mesen 工具执行 `return 1 + 1`
你应该会得到 `2` 的返回值。
再试一个真实的读内存操作（假设是 SNES 的 WRAM 地址）：
> 使用 mesen 工具执行 `return emu.read(0x7E0000)`
你应该会得到一个 0~255 的数字（该地址的字节值）。
如果这两步都正常，说明整个链路已经通了。
---
## 7. 日常使用流程
一旦设置完成，你平时的使用流程就是：
1. **启动 Mesen**，加载你想研究的 ROM。
2. **打开 Script Window**，加载 `mesen_bridge.lua` 并运行（如果之前已经加载并且勾选了自动启动，可能它会自动运行）。
3. **启动你的 MCP 客户端**（如 Claude Code），然后直接在聊天中给 LLM 下达指令。
LLM 可以自由查阅 Mesen 的 [Lua API 文档](
https://www.mesen.ca/docs/apireference.html)，然后通过 `execute_lua` 工具执行任意代码。你不需要预先把所有 API 编码到 MCP 命令中，灵活性极高。
---
## 8. 高级特性：回调管理
桥接脚本包装了 `emu.addEventCallback` 和 `emu.addMemoryCallback`，允许 LLM 注册回调函数（比如每帧执行、内存写入时触发）。**注意：注册回调时必须提供一个 label（标签）**，例如：
```lua
-- 第三参数是 label
emu.addEventCallback(fn, emu.eventType.endFrame, "frame counter")
-- 第六参数是 label
emu.addMemoryCallback(fn, emu.callbackType.write, 0x7E0010, 0x7E0010, emu.memType.snesMemory, "hp watcher")
```
MCP 服务器提供了 `clear_callbacks` 工具，用于清理这些回调：
```
clear_callbacks({ label: "frame counter" }) # 只删除该标签的回调
clear_callbacks({}) # 删除所有已跟踪的回调
```
建议在每次新会话开始时先执行 `clear_callbacks({})`，避免之前会话残留的回调干扰。
---
## 9. 故障排查常见问题
### ① “timeout: no response from Mesen Lua bridge”
这个超时提示信息里已经列出了常见原因，大多是：
- **“Allow access to I/O and OS functions” 没有开启** → 桥接无法写入文件，去设置里打开。
- **桥接脚本没有被加载**（或者被停止了）→ 重新加载并运行。
- **没有加载任何 ROM** → 桥接需要 ROM 运行才能响应（因为它是靠 `endFrame` 事件轮询的）。
- **你执行的 Lua 代码本身超时** → 超过了 Mesen 设置里的 Script timeout（我们之前设成了 10 秒），请缩短代码执行时间或增大超时。
### ② “Error from Mesen Lua: ... attempt to call a nil value”
说明你的 Lua 代码调用了当前系统不支持的 API。查阅 [Mesen API 参考](
https://www.mesen.ca/docs/apireference.html)，确认函数是否存在，并注意有些函数是平台相关的。
### ③ 客户端看不到 `mesen` 工具
- 对于 Claude Code：运行 `claude mcp list` 确认是否列出。检查你是否在项目目录下启动 `claude`（或者是否已添加用户级配置）。
- 对于其他客户端：检查启动命令和工作目录是否正确（必须为仓库根目录）。
### ④ 关于错误计数
每次 `execute_lua` 的响应末尾都会包含类似：
```
---
bridge_errors: 3
```
这是从桥接脚本加载以来累计的 Lua 错误次数。如果 LLM 看到这个数字增加，就知道可能有操作失败了（即使最后一次调用成功）。所有错误也会在 Mesen 脚本控制台和 `/tmp/mesen-mcp/mesen_errors.log` 中记录。
---
## 10. 一些注意事项
- **并发请求**：目前只支持单个请求排队执行（内部有互斥锁），对交互式逆向工作来说足够。
- **返回值类型**：Lua 表（table）会被转为 `table: 0x...` 的形式，如果返回嵌套结构，可以考虑在 Lua 中用 `json.encode` 等序列化后返回。
- **`print()` 输出**：脚本中的 `print()` 只会输出到 Mesen 脚本控制台，不会返回给 LLM。如果需要捕获输出，可以写到会话目录下的日志文件里。
---
## 11. 进一步学习
- 查看项目提供的 [演示视频](
https://github.com/gareve/mesen-lua-bridge-mcp) 了解实际工作流。
- 你可以让 LLM 直接查阅 Mesen 的 [Lua API 文档](
https://www.mesen.ca/docs/apireference.html) 并生成代码，它会自动尝试调用。
---
按照以上步骤，你应该可以在几分钟内建立起完整的开发环境。如果在使用过程中遇到任何问题，可以查看项目 README 的 “Troubleshooting” 部分，或者提交 Issue。
祝你逆向愉快！🎮
