内容
---
# MAME MCP 服务器
通过 Python 服务器控制 MAME（或任何 MCP 。
## 要求
- **MAME** 安装在 Windows 上（测试版本为 0.267+）
- **Python 3.11+**
- Python 依赖项：
```bash
pip install mcp httpx pillow mss
```
## 项目文件
| 描述 |
|-----------------------|---------------------------------------------|
| `mcp_server.py` 的 MCP 服务器（stdio）| `mame_m.lua` | 在 MAME 中加载的 Lua 脚本（） |
## 设置
### 1. 将文件复制AME 文件夹
```
C:\Users\<user>\mame\
├── mame.exe
mame_mcp_bridge.lua ← 复制到此处
├── roms\
└── ...
```
### 2. 配置 MCP
通常不需要系统范围的环境变量。仅当您的设置未使用默认值时，才在 MCP 客户端配置文件（`env`）路径。
#### 选项 A — IntelliJ IDEA (GitHub)
打开 `%LOCALAPPDATA%\github-copilot\intellij.json` 并在 `servers` 部分添加 `mame`：
```json
{
"servers": {
ame": {
"command": "C:\\Python313\\python "args": [
"-u",
"C:/Users/<user>/mame/mame_mcp_server.py"
],
"env": {
"MAME_EXE": "C:\\Users\\<user>\\mame\\mame.exe",
"MAME_ROM_PATH": "C:\\Users\\<user>\\mame\\roms",
"MAME_LUA_BRIDGE": "C:\\Users\\<user>\\mame\\mame_mcp_bridge.lua"
}
}
}
}
```
> **注意：**
> - 使用 `python.exe` 的完整路径（ `python`）：Windows Store 存根已安装的包。
> - `mcp.json` 文件可能已经包含其他已配置的 MCP 服务器 — 只需添加 `mame` 条目。
> - 保存后，**重启** MCP 服务器。
#### 选项 B — Claude Desktop
打开 `%APPDATA%\Claude\claude_desktop_config.json` 并添加：
```json
{
"mcpServers": {
"mame": {
"command": "C:\\Python313\\python.exe",
"args": ["-u", "C:\\path\\_mcp_server.py"],
"env": {
"MAME_EXE": "C:\\Users\\<user>\\mame\\mame.exe",
"MAME_ROM_PATH": "C:\\Users\\<user>\\mame\\roms",
"MAME_LUA_BRIDGE": "C:\\Users\\<user>\\mame\\mame_mcp_bridge.lua"
}
}
}
}
```
重启 Claude Desktop。
## 可用工具
| 工具 | 描述 |
|---------------------|---------------------------------------------|
| `mame_launch` | 启动 MAME 并加载 ROM |
| `mame_stop` | 终止 MAME |
| `mame_status` | 当前状态（系统、帧、暂停） |
| `mame_pause` | 暂停模拟 |
mame_resume` | 恢复模拟 |
| `mame_reset` |或硬重置 |
mame_screenshot` 截取屏幕截图（返回图像） |
| `mame_read_memory` | 从地址读取 1/2/4/8 字节 |
| `mame_read_memory_block` | 读取块（十六进制转储） |
| `mame_write_memory` | 向内存写入值 |
| `mame_get_registers`| 读取所有 CPU 寄存器 |
| `mame_set_register` | 设置 CPU 寄存器 |
| `mame_list_inputs` | 列出 I/O 端口/字段 |
| `mame_send_input` | 模拟输入（按键/ joystick） |
| `mame_list_roms` | 列出文件夹中的 ROMs |
| `mame_cheat_read` | 用于查找值的十六进制转储（作弊） |
| `mame_exec_lua` | 在 MAME 中执行任意 Lua 代码 |
## 用法
### 手动启动 MAME 和加载 Lua 桥接
如果您想手动启动 MAME（用于高级调试或在前台查看 Lua 控制台），请按照以下步骤：
1. **打开命令提示符** 并进入 MAME 文件夹：
```sh
cd C:\Users\<user>\mame
```
2. **启动 MAME**，使用所需的 ROM 和调试/控制台选项：
```sh
mame.exe pc1403 -debug -nomaximize -console
```
*(用您要使用的 ROM 替换 `pc1403`)*
3. **手动加载 Lua 桥接 MAME Lua 控制台（在控制台窗口中出现）：
```
[MAME]> dofile("mame_mcp_bridge.lua")
```
执行此命令后，基于文件的桥接将激活，您可以J 或其他客户端使用所有 MCP 工具。
> ****
> 如果您其他脚本（例如 `key.lua`），请使用：
> ```
> [MAME]> dofile("key.lua")
> ```
### 示例命令（在 或 IntelliJ Copilot
一些代码段或自然语言命令，用于控制 MAME：
"启动 PC-140调试和控制台"
（如果 MAME 已经运行并加载接，则不需要此命令）
这将执行命令mame_launch(rom="pacman")`
"显示 CPU 寄存器"
→ `mame_get_registers()`
"0xFF00 读取 256 字节的十六进制"
→ `mame_read_memory_block(address=0xFF00, length=256)`
"暂停并显示屏幕"
→ `mame_pause()`
"截取屏幕截图" → `mame_screenshot()` （*待测试！*）
...
## 技术说明
### Lua 桥接的工作原理
当 `mame_mcp_bridge.lua` 被 MAME 加载时，在启动时通过 `-autoboot_script`，它将使用**基于文件的 IPC** 与 Python MCP 服务器交换命令：
- Python 服务器将命令写入 MAME 目录中的 `mame_cmd- Lua 桥接每帧（`register_frame_done`）和每秒（`ic`）读取文件
- 它将响应写入 `mame_rsp.json`，Python 读取并删除
每个命令都是一个 JSON 文件：
```json
{"command": "read_memory", "params": {"space": ":maincpu", " 57392, "size": 1}}
```
每个响应也是一个 JSON 文件：
```json
{"status": "ok", "result": {"address": 57392, "value128, "size": 1}}
```
> **调试模式注意：** 使用 `-debug` 时，桥接通过 `register_periodic` 响应（约每秒一次）。命令最多可耗时 ~10 秒。
> 当 MAME 运行时（F5），它每帧响应（~60 次/秒）。
### 支持的 Lua`status` ·` · `resume`reset` · `hard_reset` · `read_memory `read_memory_block` · `write_memory` · `get_registers` · `set_register` · `list_inputs` · `send_input` · `cheat_read` · `exec_lua`
### exec_lua — 调试器命令和任意 Lua
`mame_exec_lua` 直接在 MAME 环境中执行 Lua 代码。实用示例：
```
# 将二进制文件加载到内存中（等效于调试器命令"）
mameua('manager.machine.debugger:command("load tmp.bin,e030:maincpu# 设置断点
mame_exec_lua('manager.debugger:command("030")')
#.lua 进行键盘自动化
_exec_lua('dofile.lua")')
```
> **注意：** `key.lua` 中的 `key()` / `keyfile()` 函数使用 `emu.wait()`，需要 Lua 控制台协程上下文> 它们必须从 Lua 控制台（如果 MAME 使用 `-console` 和 `CREATE_NEW_CONSOLE` 启动运行。
###截图
屏幕截图使用 `mss` 捕获视器。如果您更喜欢仅捕获 MAME 窗口，可以使用 `pygetwindow` 扩展代码：
```python
pip install pygetwindow
```
## 故障**首次启动时MCP error -320 Connection closed` 错误** 服务器使用 `FastMCP`（mcp >= 1.0）。确保为正确的 Python 安装了 `mcp` 包：
`C:\Python313\python.exe -c "from mcp.server.fastmcp import FastMCP; print('ok')"`
**"桥接在 30 秒内未响应"**
→ 在调试模式下，桥接速度慢（~6-10 秒/响应）。正常。
→ 如果 MAME 正在运行（未暂停），响应将在不到 1 秒内到达。
→ 检查 MAME 目录中是否存在陈旧的 `mame_cmd.json` / `mame_rsp.json` 文件。
**"未找到 mame.exe"**
→ 在 `mcp.json` 文件中设置 `MAME_EXE` 环境变量。
**Lua 中出现 `Fatal error: module 'socket' not found` 错误**
→ LuaSocket 在 MAME 0.267 中不可用。桥接使用文件 IPC：无问题。
**MAME Lua 控制台不可见**
→ MAME 使用 `CREATE_NEW_CONSOLE` 启动 — 应该打开一个单独的控制台窗口。
它不出现，请从 `cmd` 手动启动：`cd C:\Users\<user>\mameame.exe pc140debug -nomaximize -console`
**`emu 在 `mame_exec` 中不起作用**
→ `emu.wait()` 需要 Lua 控制台协程上下文。请直接从 MAME 控制使用它。
##扩展
- [ ] 内存地址（通知时）
- [ MAME `-aviwrite` 进行视频录制 [ ] 通过 Lua器钩子进行 CPU 断点
- [ RAM 搜索（类似作弊引擎）
- [档保存/加载
