dmang-dev/mcp-dolphin

npm version npm downloads CI License: MIT Snyk Socket Bundlephobia npmgraph

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

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)
dolphin_reset	Emulation soft-reset (pause/resume deferred to v0.2 — see Known limitations)
dolphin_frame_advance	Wait N frames (TAS sequencing)
dolphin_save_state / dolphin_load_state	Slot-based savestate (0-255)

GameCube + Wii address space (cheat sheet)

Range	Region
0x80000000-0x817FFFFF	MEM1 main RAM (24 MiB) — GC + Wii
0x80000020	OS_GLOBALS — disc ID, FST pointer, etc.
0x90000000-0x93FFFFFF	MEM2 (64 MiB) — Wii only
0xCC000000+	Flipper / Hollywood I/O — reads usually safe, writes can wedge
0xCD000000+	Wii-only Hollywood registers

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

Env var	Default	Purpose
DOLPHIN_BRIDGE_HOST	127.0.0.1	Bridge host (the Dolphin process is local, so this rarely changes)
DOLPHIN_BRIDGE_PORT	55355	Bridge port (must match LISTEN_PORT in mcp_bridge.py)
DOLPHIN_TIMEOUT_MS	10000	Per-call timeout
MCP_DOLPHIN_DEBUG	unset	Set to 1 to trace every TX message on stderr

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

Troubleshooting

Symptom	Cause / Fix
Dolphin bridge not reachable	Dolphin not running, script not loaded in Scripting panel, or wrong port. Check Dolphin's Log window for [mcp-bridge] listening on ....
unknown method: <something> from bridge	Bridge script is older than mcp-dolphin. Re-export with npx mcp-dolphin --print-bridge > mcp_bridge.py and reload in Dolphin.
Memory reads return 0xFFFFFFFF or error	Address is unmapped on the current title. MEM2 (0x90000000+) is Wii-only; reading it on a GameCube game returns garbage.
Controller input has no effect	Game expects input on a different port. Try port: 0 first, then 1-3. For Wii games requiring motion, this v0.1.0 doesn't cover Wii Remote pointer/accel yet.
Tool calls hang ~10 s then time out	Bridge script crashed inside Dolphin. Open Felk's Scripting panel, remove the script, re-add it.

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.