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

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:

claude mcp list
# retroarch: mcp-retroarch - ✓ Connected

Claude Desktop

Edit claude_desktop_config.json:

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

Restart Claude Desktop after editing.

Configuration

Tools

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

Tested cores

Verified end-to-end against mcp-retroarch:

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

Development

npm install
npm run dev      # tsc --watch

Smoke test against a running RetroArch:

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