内容
# mcp-dolphin
[](https://www.npmjs.com/package/mcp-dolphin)
[](https://www.npmjs.com/package/mcp-dolphin)
[](https://github.com/dmang-dev/mcp-dolphin/actions/workflows/ci.yml)
[](LICENSE)
[](https://snyk.io/test/npm/mcp-dolphin)
[](https://socket.dev/npm/package/mcp-dolphin)
[](https://bundlephobia.com/package/mcp-dolphin)
[](https://npmgraph.js.org/?q=mcp-dolphin)
一个适用于 **Dolphin** （GameCube + Wii）的 [MCP](https://modelcontextprotocol.io) 服务器 — 驱动内存读写、控制器输入（GameCube + Wii Remote）、暂停/恢复/重置、存档状态和帧推进，来自与MCP兼容的客户端（Claude Desktop, Claude Code等）。
## 你可以用它做什么
- **读写模拟的PowerPC内存** — 8/16/32/64位，MEM1 + MEM2
- **发送控制器输入** — GameCube（数字 + 模拟摇杆 + 触发器），Wii Remote（按钮 + 红外指针 + 加速度计 + MotionPlus角速度）
- **重置** 模拟器（暂停/恢复功能在v0.1.0中不可用 — 见已知限制）
- **保存/加载状态** 到编号槽（0-255；1-10映射到Dolphin中的F1-F10）
- **帧推进** — 同步等待N帧，用于TAS风格的精度
尚未在v0.1.0中实现（延迟到后续版本）：
- Wii Remote运动（指针，加速度计，摆动，摇晃，倾斜）
- Nunchuk / Classic Controller / GBA-via-Wii输入
- 内存断点，寄存器访问，截图
## 架构（和硬性要求）
```
┌─────────────────────────────────────────────────┐
│ Dolphin (Felk的fork — 需要，不是主线) │
│ │
│ mcp_bridge.py通过脚本面板加载 │
│ └─ TCP服务器在127.0.0.1:55355 │
└─────────────────────────────────────────────────┘
↕ TCP环路（newline-delimited JSON）
┌─────────────────────────────────────────────────┐
│ mcp-dolphin (Node.js — 此软件包) │
└─────────────────────────────────────────────────┘
↕ MCP标准输入输出
MCP客户端（Claude等）
```
**主线Dolphin没有Python脚本支持。** mcp-dolphin与[Felk积极维护的Dolphin分支](https://github.com/Felk/dolphin)通信，它嵌入了Python，可以直接访问内存、控制器、存档状态和帧循环。主线Dolphin的Python PR ([#7064](https://github.com/dolphin-emu/dolphin/pull/7064)) 自2022年以来一直停滞；Lua分支 ([dolphinWatch](https://github.com/TwitchPlaysPokemon/dolphinWatch), [SwareJonge/Dolphin-Lua-Core](https://github.com/SwareJonge/Dolphin-Lua-Core)) 已经废弃。Felk是唯一的活跃脚本路径。
## 一次性设置
### 1. 安装Felk的Dolphin分支
从[Felk/dolphin Releases](https://github.com/Felk/dolphin/releases)获取一个构建 — 目前是 **Python Scripting Preview 4** （2025年12月）。解压到一个可以找到的位置。它是一个常规的Dolphin构建，加上一个 **脚本** 面板，在“视图”菜单下。
如果加载桥时出现Python错误，请启用脚本日志类型：**视图 → 显示日志配置 → 勾选脚本** （将详细程度设置为“信息”或“错误”），然后 **视图 → 显示日志** 以使日志窗口可见。
### 2. 打印桥脚本并加载它
```bash
npx -y mcp-dolphin --print-bridge > mcp_bridge.py
```
然后在Felk的Dolphin中：
1. **视图 → 脚本** 打开脚本面板。
2. 点击 **添加新脚本** 并选择您刚刚编写的 `mcp_bridge.py`。
3. 在Dolphin的日志窗口中验证 — 您应该看到 `[mcp-bridge] listening on 127.0.0.1:55355 (bridge v0.1.0)`。
脚本在Dolphin打开时持续运行。 从脚本面板中删除它以停止桥。
### 3. 在MCP客户端中注册mcp-dolphin
**Claude Code:**
```bash
claude mcp add dolphin --scope user mcp-dolphin
```
**Claude Desktop** — 编辑 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"dolphin": {
"command": "npx",
"args": ["-y", "mcp-dolphin"]
}
}
}
```
在编辑后重启MCP客户端。
### 4. 验证
在Dolphin中加载GameCube或Wii游戏，然后要求代理调用 `dolphin_ping`。您应该看到 `OK — bridge v0.1.0 (Felk Python fork)`。
## 工具
| 工具 | 描述 |
|------|-------------|
| `dolphin_ping` | 存活探测 + 桥版本嗅探 |
| `dolphin_get_info` | 报告桥版本和Dolphin标签 |
| `dolphin_read8/16/32/64` | 读取PowerPC内存（大端） |
| `dolphin_read_range` | 以十六进制转储读取最多64 KiB |
| `dolphin_write8/16/32/64` | 写入PowerPC内存 |
| `dolphin_press_gc_buttons` | 设置GameCube控制器状态（端口 + 按钮/轴字典） |
| `dolphin_press_wiimote_buttons` | 设置Wii Remote按钮状态 |
| `dolphin_set_wiimote_pointer` | 设置Wii Remote红外指针位置（端口 + x + y） |
| `dolphin_set_wiimote_acceleration` | 设置Wii Remote加速度计（端口 + x + y + z，~g单位） |
| `dolphin_set_wiimote_angular_velocity` | 设置Wii MotionPlus角速度（端口 + x + y + z，rad/s） |
| `dolphin_reset` | 模拟器软重置（暂停/恢复功能延迟到v0.2 — 见已知限制） |
| `dolphin_frame_advance` | 等待N帧（TAS排序） |
| `dolphin_save_state` / `dolphin_load_state` | 基于槽的存档状态（0-255） |
## GameCube + Wii 地址空间（速查表）
| 范围 | 区域 |
|-------|--------|
| `0x80000000-0x817FFFFF` | MEM1主RAM（24 MiB） — GC + Wii |
| `0x80000020` | `OS_GLOBALS` — 光盘ID，FST指针等 |
| `0x90000000-0x93FFFFFF` | MEM2（64 MiB） — **仅限Wii** |
| `0xCC000000+` | Flipper / Hollywood I/O — 读取通常安全，写入可能卡住 |
| `0xCD000000+` | Wii专用Hollywood寄存器 |
PowerPC在硬件上是 **大端** 的。桥在读写时处理字节交换 — 传递和接收游戏逻辑上看到的值，而不是字节顺序。
## 控制器输入
### GameCube (`dolphin_press_gc_buttons`)
```json
{
"port": 0,
"state": {
"A": true, "B": false, "Start": true,
"StickX": 200, "StickY": 128,
"TriggerLeft": 0, "TriggerRight": 255
}
}
```
- 数字按钮：`A, B, X, Y, Z, Start, L, R, Up, Down, Left, Right`
- 模拟轴：`StickX, StickY, CStickX, CStickY` （0-255，128 = 中心）
- 触发器：`TriggerLeft, TriggerRight` （0-255，0 = 释放）
- 省略的键默认为释放 / 中心。
### Wii Remote (`dolphin_press_wiimote_buttons`)
```json
{ "port": 0, "state": { "A": true, "Plus": true, "Up": true } }
```
- 按钮：`A, B, One, Two, Plus, Minus, Home, Up, Down, Left, Right`
- v0.1.0仅覆盖按钮 — 运动，指针，Nunchuk，Classic Controller延迟到后续版本。
## 配置
| 环境变量 | 默认值 | 目的 |
|---|---|---|
| `DOLPHIN_BRIDGE_HOST` | `127.0.0.1` | 桥主机（Dolphin进程是本地的，因此此选项很少更改） |
| `DOLPHIN_BRIDGE_PORT` | `55355` | 桥端口（必须与 `mcp_bridge.py` 中的 `LISTEN_PORT` 匹配） |
| `DOLPHIN_TIMEOUT_MS` | `10000` | 每次调用超时 |
| `MCP_DOLPHIN_DEBUG` | 未设置 | 设置为 `1` 以在stderr上跟踪每个TX消息 |
如果更改端口，请编辑 `mcp_bridge.py` （在您的脚本目录中）和设置 `DOLPHIN_BRIDGE_PORT`。
## 故障排除
| 症状 | 原因 / 修复 |
|---|---|
| `Dolphin bridge not reachable` | Dolphin未运行，脚本未在脚本面板中加载，或端口错误。 在Dolphin的日志窗口中检查 `[mcp-bridge] listening on ...`。 |
| 来自桥的 `unknown method: <something>` | 桥脚本比mcp-dolphin旧。 使用 `npx mcp-dolphin --print-bridge > mcp_bridge.py` 重新导出并在Dolphin中重新加载。 |
| 内存读取返回 0xFFFFFFFF 或错误 | 地址在当前标题中未映射。 MEM2 (`0x90000000+`) 是Wii专用的； 在GameCube游戏上读取它会返回垃圾。 |
| 控制器输入无效果 | 游戏期望在不同端口接收输入。 尝试 `port: 0`，然后是1-3。 对于需要运动的Wii游戏，v0.1.0尚不支持Wii Remote指针/加速度计。 |
| 工具调用超时约10秒后超时 | 桥脚本在Dolphin内部崩溃。 打开Felk的脚本面板，删除脚本，重新添加。 |
## 使用MCP Inspector调试
使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 浏览和调用此服务器的工具，交互式：
```bash
npm run inspector
```
如果您在上次 `npm install` 后编辑了 `src/`，请先构建（`npm run build`，或保持 `npm run dev` 运行）。 使用 `DOLPHIN_BRIDGE_HOST` / `DOLPHIN_BRIDGE_PORT` （默认为 `127.0.0.1:55355`）覆盖桥地址。 `tools/list` 即使没有连接Dolphin也能工作； **调用** 工具需要Felk的Dolphin运行 `bridge/mcp_bridge.py`。
## 许可证
MIT — 见 [LICENSE](LICENSE)。
