dmang-dev/mcp-dolphin

An MCP server for **Dolphin** (GameCube + Wii) — drives memory r/w, controller input (GameCube + Wii Remote), pause/resume/reset, savestates, and frame advance from MCP-compatible clients (Claude Desktop, Claude Code, etc.).
What you can do with it
- **Read & write emulated PowerPC memory** — 8/16/32/64-bit, MEM1 + MEM2
- **Send controller input** — GameCube (digital + analog sticks + triggers), Wii Remote (buttons + IR pointer + accelerometer + MotionPlus angular velocity)
- **Reset** the emulator (pause/resume not in v0.1.0 — see Known limitations)
- **Save / load state** to numbered slots (0-255; 1-10 map to F1-F10 in Dolphin)
- **Frame advance** — wait N frames synchronously for TAS-style precision
Not yet wired in v0.1.0 (deferred to a later release):
- Wii Remote motion (pointer, accelerometer, swing, shake, tilt)
- Nunchuk / Classic Controller / GBA-via-Wii input
- Memory breakpoints, register access, screenshots
Architecture (and the hard prerequisite)
**Mainline Dolphin does not have Python scripting.** mcp-dolphin talks to Felk's actively-maintained Dolphin fork which embeds Python with first-class access to memory, controllers, savestates, and the frame loop. Mainline Dolphin Python PRs (#7064) have been stuck since 2022; the Lua forks (dolphinWatch, SwareJonge/Dolphin-Lua-Core) are dead. Felk is the only living scripting path.
One-time setup
1. Install Felk's Dolphin fork
Grab a build from Felk/dolphin Releases — currently **Python Scripting Preview 4** (December 2025). Unzip it somewhere you can find. It's a regular Dolphin build plus a **Scripting** panel under the View menu.
If you see Python errors when loading the bridge, enable the Scripting log type: **View → Show Log Configuration → check Scripting** (set verbosity to "Info" or "Error"), then **View → Show Log** so the log window is visible.
2. Print the bridge script and load it
Then in Felk's Dolphin:
1. **View → Scripting** to open the scripting panel.
2. Click **Add New Script** and pick the mcp_bridge.py you just wrote.
3. Verify in Dolphin's Log window — you should see [mcp-bridge] listening on 127.0.0.1:55355 (bridge v0.1.0).
The script keeps running as long as Dolphin is open. Remove it from the Scripting panel to stop the bridge.
3. Register mcp-dolphin in your MCP client
**Claude Code:**
**Claude Desktop** — edit claude_desktop_config.json:
Restart your MCP client after editing.
4. Verify
Load a GameCube or Wii game in Dolphin, then ask the agent to call dolphin_ping. You should see OK — bridge v0.1.0 (Felk Python fork).
Tools
| Tool | Description |
|------|-------------|
| dolphin_ping | Liveness probe + bridge-version sniff |
| dolphin_get_info | Report bridge version and Dolphin label |
| dolphin_read8/16/32/64 | Read PowerPC memory (big-endian) |
| dolphin_read_range | Bulk read up to 64 KiB as hex dump |
| dolphin_write8/16/32/64 | Write PowerPC memory |
| dolphin_press_gc_buttons | Set GameCube controller state (port + button/axis dict) |
| dolphin_press_wiimote_buttons | Set Wii Remote button state |
| dolphin_set_wiimote_pointer | Set Wii Remote IR pointer position (port + x + y) |
| dolphin_set_wiimote_acceleration | Set Wii Remote accelerometer (port + x + y + z, ~g units) |
| dolphin_set_wiimote_angular_velocity | Set Wii MotionPlus angular velocity (port + x + y + z, rad/s) |