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)

┌─────────────────────────────────────────────────┐
│ Dolphin (Felk's fork — required, not mainline)  │
│                                                 │
│   mcp_bridge.py loaded via Scripting panel      │
│   └─ TCP server on 127.0.0.1:55355              │
└─────────────────────────────────────────────────┘
                  ↕ TCP loopback (newline-delimited JSON)
┌─────────────────────────────────────────────────┐
│ mcp-dolphin (Node.js — this package)            │
└─────────────────────────────────────────────────┘
                  ↕ MCP stdio
              MCP client (Claude etc.)

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

npx -y mcp-dolphin --print-bridge > mcp_bridge.py

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 mcp add dolphin --scope user mcp-dolphin

Claude Desktop — edit claude_desktop_config.json:

{
  "mcpServers": {
    "dolphin": {
      "command": "npx",
      "args": ["-y", "mcp-dolphin"]
    }
  }
}

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

GameCube + Wii address space (cheat sheet)

PowerPC is big-endian on hardware. The bridge handles byte-swap on read/write — pass and receive the value the game logically sees, not the byte order.

Controller input

GameCube (dolphin_press_gc_buttons)

{
  "port": 0,
  "state": {
    "A": true, "B": false, "Start": true,
    "StickX": 200, "StickY": 128,
    "TriggerLeft": 0, "TriggerRight": 255
  }
}

• Digital buttons: A, B, X, Y, Z, Start, L, R, Up, Down, Left, Right
• Analog axes: StickX, StickY, CStickX, CStickY (0-255, 128 = center)
• Triggers: TriggerLeft, TriggerRight (0-255, 0 = released)
• Omitted keys default to released / center.

Wii Remote (dolphin_press_wiimote_buttons)

{ "port": 0, "state": { "A": true, "Plus": true, "Up": true } }

• Buttons: A, B, One, Two, Plus, Minus, Home, Up, Down, Left, Right
• v0.1.0 covers buttons only — motion, pointer, Nunchuk, Classic Controller deferred to a future release.

Configuration

If you change the port, edit both mcp_bridge.py (in your scripts dir) and set DOLPHIN_BRIDGE_PORT.

Troubleshooting

Debugging with the MCP Inspector

Browse and call this server's tools interactively with the MCP Inspector:

npm run inspector

Build first if you've edited src/ since your last npm install (npm run build, or keep npm run dev running). Override the bridge address with DOLPHIN_BRIDGE_HOST / DOLPHIN_BRIDGE_PORT (default 127.0.0.1:55355). tools/list works even without Dolphin connected; calling a tool needs Felk's Dolphin running bridge/mcp_bridge.py.

License

MIT — see LICENSE.