dmang-dev/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
Requirements
- **RetroArch** (any recent version) with Network Commands enabled
- **Node.js 22+**
Install
Option A — install from npm (recommended)
Option B — npx (no install)
Option C — clone and develop
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:**
Then launch any libretro core + game. The NCI is always-on once enabled — no script to load.
Register with your MCP client
Claude Code
Verify:
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 |
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") |