mcp-retroarch

mcp-retroarch

       

An MCP server that bridges Claude (and any other MCP client) to RetroArch via its built-in Network Control Interface (UDP, port 55355).

Works against any libretro core (NES, SNES, Genesis, GB/GBC/GBA, PSX, N64, etc.) — give the model memory r/w, save-state automation, screenshot, pause / frame-advance / reset, and on-screen messages.

What it can do

| Capability | Available? | Notes | |---|---|---| | Memory read / write | ✅ | Two paths: READ_CORE_MEMORY (system memory map, preferred) and READ_CORE_RAM (CHEEVOS, fallback) | | Save / load state | ✅ | Current slot or explicit slot for load; save is current-slot-only (NCI limitation) | | Screenshot | ✅ | Saved to RetroArch's configured screenshot directory | | Pause / frame advance | ✅ | PAUSE_TOGGLE flips state; FRAMEADVANCE steps one frame | | Reset | ✅ | Hard-reset the running game | | On-screen message | ✅ | Useful for "look here" cues during scripted runs | | Game info | ✅ | Title, system, CRC32 | | Game-pad input | ❌ | NCI doesn't expose this. RetroArch has a separate "Remote RetroPad" core on UDP port 55400 that does, but it requires loading that specific core (you can't drive an existing emulation core through it). Not in scope for v0.1.0. |

If you need game-pad input on Game Boy Advance specifically, see mcp-mgba. For PCSX2 (memory + savestate only, no input/screenshot), see mcp-pine.

How it works

+----------------+    stdio     +-----------------+   UDP :55355  +-----------------+
|   MCP client   |   JSON-RPC   |  mcp-retroarch  |  text proto   |    RetroArch    |
|  (Claude etc)  | -----------> |    (Node.js)    | ------------> |  (NCI enabled)  |
+----------------+              +-----------------+               +-----------------+

Requirements

• RetroArch (any recent version) with Network Commands enabled
• Node.js 22+

Install

Option A — install from npm (recommended)

npm install -g mcp-retroarch

Option B — npx (no install)

npx -y mcp-retroarch

Option C — clone and develop

git clone https://github.com/dmang-dev/mcp-retroarch
cd mcp-retroarch
npm install

Enable RetroArch's Network Control Interface

Either:

• GUI: Settings → Network → Network Commands → ON, then confirm Network Cmd Port is 55355 (the default)
• Or via retroarch.cfg:

  network_cmd_enable = "true"
  network_cmd_port   = "55355"

Then launch any libretro core + game. The NCI is always-on once enabled — no script to load.

Register with your MCP client

Claude Code

claude mcp add retroarch --scope user mcp-retroarch

Verify: ```bash claude mcp list

retroarch: mcp-retroarch - ✓ Connected

### Claude Desktop

Edit `claude_desktop_config.json`:

| Platform | Path |
|---|---|
| macOS    | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows  | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux    | `~/.config/Claude/claude_desktop_config.json` |

{ "mcpServers": { "retroarch": { "command": "mcp-retroarch" } } } ```

Restart Claude Desktop after editing.

Configuration

| Env var | Default | Purpose | |---------------------|---------------|---------| | RETROARCH_HOST | 127.0.0.1 | UDP destination host | | RETROARCH_PORT | 55355 | UDP port (must match network_cmd_port in retroarch.cfg) |

Tools

| Tool | Description | |------|-------------| | retroarch_ping | Verify reachability — returns RetroArch version | | retroarch_get_status | State (playing/paused), system, game, CRC32 | | retroarch_get_config | Read named RetroArch config values (e.g. savestate_directory) | | retroarch_read_memory / retroarch_write_memory | Memory r/w via system memory map | | retroarch_read_ram / retroarch_write_ram | Memory r/w via CHEEVOS address space (fallback when no memory map) | | retroarch_pause_toggle | Toggle pause state | | retroarch_frame_advance | Step one frame (only effective while paused) | | retroarch_reset | Hardware-reset the running game | | retroarch_screenshot | Save a screenshot to RetroArch's screenshot directory | | retroarch_show_message | Display a notification on the RetroArch window | | retroarch_save_state_current | Save to currently-selected slot | | retroarch_load_state_current | Load from currently-selected slot | | retroarch_load_state_slot | Load from explicit slot number | | retroarch_state_slot_plus / retroarch_state_slot_minus | Change current slot pointer (NCI has no "set slot to N") |

See docs/RECIPES.md for end-to-end examples.

Tested cores

Verified end-to-end against mcp-retroarch:

| System | Core | read_memory | read_ram | Notes | |---|---|---|---|---| | Game Boy Advance | mgba_libretro | ✅ | ✅ | GBA interrupt vector table visible at 0x0000 (d3 00 00 ea ...) | | NES | mesen_libretro | ✅ (only NES core tested that does) | ✅ | Full 16-bit NES address space exposed. WRAM at 0x0000-0x07FF, mirrored to 0x1FFF. CHEEVOS bounded to first 64 KB. | | NES | nestopia_libretro | ❌ no memory map | ✅ | CHEEVOS only. 64 KB bound. For NES + memory map, prefer Mesen. | | SNES | snes9x_libretro | ❌ no memory map | ✅ | CHEEVOS bounded to ~128 KB (matches SNES WRAM size). 65C816 RTS opcodes (60) visible in code regions. | | Sega Mega Drive / Genesis | genesis_plus_gx_libretro | ❌ no memory map | ⚠️ sparse | CHEEVOS exposes some 68K WRAM addresses but fails at others ("no error message"). Usable if you know specific addresses; blanket sweep doesn't work. | | Nintendo 64 | mupen64plus_next_libretro | ✅ | ✅ | Full N64 RAM exposed. KSEG0 mirror is faithful — read_memory(0x80000000) returns the same bytes as read_memory(0x0). Bound is the connected RAM size (4 MB without Expansion Pak, 8 MB with). | | PlayStation 1 | swanstation_libretro | ❌ no memory map | ✅ | CHEEVOS only. PSX main RAM begins around CHEEVOS offset 0x010000 (lower addresses are typically zero). |

Patterns observed

• Most libretro cores don't advertise a system memory map to NCI — they implement only the CHEEVOS read API. Of those tested, only Mesen (NES) and Mupen64Plus-Next (N64) expose a system memory map. Both also expose CHEEVOS, so they're strictly better.
• System memory maps are faithful to real hardware — Mupen64Plus-Next preserves the N64's KSEG0 mirror (0x80000000 reads as 0x0); Mesen preserves the NES's WRAM mirroring (0x1000 reads as 0x0). This is great for anyone using the bridge alongside disassembly.
• CHEEVOS bounds match the system's main RAM size — NES exposes 64 KB, SNES 128 KB, etc. Reads past the bound fail with "no error message".
• When choosing a core for memory work, prefer the one with a system memory map if available.

If you've tested another core, please open a PR adding it to this table.

Troubleshooting

| Symptom | Cause / Fix | |---|---| | RetroArch query timed out | Network Commands aren't enabled in RetroArch, or the port doesn't match RETROARCH_PORT. Confirm network_cmd_enable = "true" in retroarch.cfg. Also: UDP datagrams can be dropped under load even on loopback — if a single call times out but a retry succeeds, that's the cause. The bridge doesn't auto-retry; just call again. | | READ_CORE_MEMORY failed: no memory map defined | The loaded libretro core doesn't advertise a system memory map. Try retroarch_read_ram (CHEEVOS path) — many cores expose CHEEVOS even without a memory map. Confirmed for SwanStation (PSX); use read_ram for that core. | | READ_CORE_MEMORY failed: no descriptor for address | The address isn't covered by the core's memory map. Either a different core would expose it, or the address you want is outside the system bus (e.g. video memory in some cores). | | Screenshots don't appear where I expect | RetroArch saves to its configured screenshot directory. The NCI doesn't expose screenshot_directory via GET_CONFIG_PARAM, so check the value via RetroArch's GUI: Settings → Directory → Screenshot. | | Can't save to a specific state slot directly | NCI limitation, not a bug. The protocol only exposes "save to current slot" — you have to walk the slot pointer to your target with state_slot_plus/state_slot_minus, then save. |

Development

npm install
npm run dev      # tsc --watch

Smoke test against a running RetroArch: ``bash node .scratch/smoke.cjs ``

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 target with RETROARCH_HOST / RETROARCH_PORT (default 127.0.0.1:55355). tools/list works even without RetroArch connected; calling a tool needs RetroArch running with Network Commands enabled.

License

MIT

Related

• mcp-mgba — Game Boy Advance via mGBA's Lua bridge (includes button input + screenshot)
• mcp-pine — PINE-speaking emulators (PCSX2 et al.) — memory + savestate only
• RetroArch NCI documentation