dolphin-decomp-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
dolphin-decomp-mcp
A small, general-purpose tool surface over Dolphin's DAP debug server for decompilation / reverse-engineering work on GameCube & Wii titles.
It exposes 12 primitives — read/write memory and registers, disassemble, run control, code & data breakpoints, a PPC assembler, code injection, detours, and non-halting realtime watches/freezes — as an MCP server (for an agent like Claude Code) and an equivalent CLI (for manual poking). Both front-ends share the exact same handlers, so behaviour can't drift.
The tools are deliberately low-level. The agent composes them into whatever it needs; the three headline workflows fall out of composition (see Recipes).
Requirements
A Dolphin built from the
feature/dap-serverbranch with the DAP server enabled (see below). This project talks to that server; it does not embed one.Python ≥ 3.10.
For the assembler tools: the
powerpc-eabi-*binutils. This project reuses the ones the melee decomp tree ships underbuild/binutils. Point it elsewhere withDOLPHIN_DECOMP_BINUTILS=/path/to/dir.For the MCP server front-end only:
pip install mcp. The CLI and the Python API need no third-party packages.
Related MCP server: DuckStation MCP
Install
cd dolphin-decomp-mcp
python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[mcp,dev]' # drop [mcp] if you only want the CLI
pytest -q # 21 tests, no emulator neededConnecting to Dolphin
Start Dolphin's DAP server. Prefer a Unix socket — it is gated by
filesystem permissions. The TCP transport in this fork binds an unauthenticated
debug server that grants full guest-memory read/write and code injection; if you
use TCP, keep it on loopback (127.0.0.1) and off any untrusted network. (A
local patch pinning the fork's TCP bind to loopback lives in the sibling
dolphin-dap checkout.)
dolphin-emu-nogui \
-C Dolphin.General.DAPSocket=/tmp/dolphin-decomp.sock \
-C Dolphin.General.DAPStopOnEntry=true \
-v Null --platform headless \
--exec /path/to/GALE01.iso
# optional: --debug-elf /path/to/main.elf (adds DWARF 1.1 line info / symbols)Then point either front-end at it via --socket / --port or the env vars
DOLPHIN_DAP_SOCKET, DOLPHIN_DAP_HOST, DOLPHIN_DAP_PORT.
MCP server (agent-facing)
Run it over stdio:
dolphin-decomp-mcp --socket /tmp/dolphin-decomp.sockRegister it with Claude Code (.mcp.json in your project, or claude mcp add):
{
"mcpServers": {
"dolphin": {
"command": "/abs/path/dolphin-decomp-mcp/.venv/bin/dolphin-decomp-mcp",
"args": ["--socket", "/tmp/dolphin-decomp.sock"],
"env": { "DOLPHIN_DECOMP_BINUTILS": "/abs/path/melee/build/binutils" }
}
}
}The connection to Dolphin is lazy and reconnects if the socket drops, so the MCP server can start before the emulator is up.
CLI (manual)
Every tool is a subcommand (the dolphin_ prefix is dropped). Scalars are
positional/flag args; object/array args are JSON strings. Output is JSON.
dolphin-decomp --socket /tmp/dolphin-decomp.sock session status
dolphin-decomp --socket /tmp/dolphin-decomp.sock read 0x80000000 16
dolphin-decomp --socket /tmp/dolphin-decomp.sock read 0x80003100 4 --format disasm
dolphin-decomp --socket /tmp/dolphin-decomp.sock control pause
dolphin-decomp --socket /tmp/dolphin-decomp.sock inject $'li r3, 1\nblr'
dolphin-decomp --socket /tmp/dolphin-decomp.sock breakpoints --data '[{"address":2147483648,"access":"write"}]'
dolphin-decomp assemble $'li r3, 0x1234\nblr' # no emulator neededThe tools
Tool | What it does |
| status / attach / launch / restart / terminate / disconnect |
| read memory as hex, or as disassembly |
| write raw bytes (hex) to memory |
| read all registers of the top frame; optionally write some first |
| evaluate a PPC debugger expression ( |
| backtrace the stopped core (who called / who wrote) |
| continue / pause / step_over / step_in / step_out / goto — returns the resulting stop |
| set code breakpoints and/or data watchpoints (authoritative) |
| PPC (Gekko) asm text → machine-code bytes, no emulator needed |
| assemble (or take hex) and write code into a cave or a fixed address |
| install a transparent detour at an instruction (observe or replace) |
| non-halting realtime memory watch/poll, and freeze/unfreeze |
Recipes
Find the writer (reverse breakpoint). What corrupts 0x8045C000?
dolphin_breakpoints data=[{address: 0x8045C000, access: "write"}]dolphin_control continue→ stops withreason: "data breakpoint", PC = the writing instruction.dolphin_stack+dolphin_registers→ the culprit and its inputs.
Call a function / test a hypothesis. Does fn(0x10) return what you think?
dolphin_control goto <fn_entry>;dolphin_registers writes={r3: 0x10}.dolphin_breakpoints code=[{address: <caller_return_or_blr>}].dolphin_control continue; read the result fromr3viadolphin_registers.
Test a code change live. Try a fix without rebuilding the game.
Patch in place:
dolphin_inject code="<asm>" address=<site>(read it first if you want to restore), orObserve/replace non-destructively:
dolphin_detour target=<fn> body="<asm>"(end withb-to-trampoline to observe, orblrafter settingr3to replace), thendolphin_control continueand verify.
Layout
dolphin_decomp/
dap.py # framed DAP client core + event pump (no deps)
session.py # high-level Dolphin operations (no deps)
ppc.py # powerpc-eabi assembler wrapper (no deps)
tools.py # the 12-tool registry + Backend (shared by both front-ends)
server.py # MCP server (needs `mcp`)
cli.py # CLI (no deps)
tests/ # framing, session-over-mock, assembler; mcp_smoke.py is live-onlyLicense
MIT.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Evidence-oriented REA + Ghidra static-analysis workflows, read-only PE32 and Delphi VMT tools.
GitMCP-ready KB for SMW (SNES) reverse engineering.
Self-hosted MCP server: 26 deterministic dev, security, and EVM tools.
Read-only MCP server for the WebAssembly spec: instructions, types, sections, search, proposals.
Related MCP Servers
- AlicenseAqualityBmaintenanceAn 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.).2045 npm6MIT
- AlicenseNot gradedqualityDmaintenanceEnables debugging of PlayStation games through DuckStation by providing MCP tools for execution control, register access, memory inspection, breakpoints, process management, and log analysis.MIT
- AlicenseNot gradedqualityCmaintenanceReverse engineering against a running Windows process instead of the file on disk: memory reads, pattern and value scanning, disassembly of the code that actually executed, resolved IAT thunks, caller-chain tracing, and structure recovery. Complements the Ghidra and IDA servers rather than replacing them — correlate_addr maps a runtime address back to a module and RVA.MIT
- FlicenseBqualityCmaintenanceEnables controlling and inspecting a running Dolphin emulator through its Debug Adapter Protocol, with persistent connections, task-oriented tools, and a raw request escape hatch for execution, breakpoints, stack/variables, memory, disassembly, sources, watches, scans, and code injection.16-