Log inSubmit server
MCP Retroarch logo

MCP Retroarch

by dmang-dev

Controls RetroArch over MCP for memory inspection, save states, screenshots, pausing, resets, and frame stepping.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install MCP Retroarch

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "dmang-dev-mcp-retroarch": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-retroarch"
      ],
      "env": {
        "RETROARCH_HOST": "YOUR_VALUE_HERE",
        "RETROARCH_PORT": "YOUR_VALUE_HERE"
      }
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Values are written into the snippet above so you can paste it as is. They never leave your browser.

Install not yet sandbox-tested— the server itself is confirmed live (we called its tools/list endpoint). The stdio install command is a separate, ongoing check.

Overview

The dmang-dev/mcp-retroarch MCP server connects MCP clients to RetroArch through its Network Control Interface over UDP. It exposes tools for emulator status, configuration reads, two memory address spaces, save-state management, screenshots, pause and frame control, resets, and on-screen messages. Use it for scripted emulator inspection, debugging, memory experiments, or reproducible state workflows when RetroArch is running with Network Commands enabled. It does not provide game-pad input.

Use cases

  • Inspect emulator memory during debugging
  • Create rollback points before memory writes
  • Step through gameplay one frame at a time
  • Capture screenshots after scripted emulator actions
  • Read game identity and runtime status

Key features

  • RetroArch NCI connectivity over UDP
  • System-map and CHEEVOS memory reads and writes
  • Current-slot and explicit-slot save-state operations
  • Pause, frame advance, reset, and screenshots
  • RetroArch configuration and game status queries
  • On-screen notification messages

Tools17

What MCP Retroarch lets your agent do. Expand a tool for its parameters.

Verified live~8.7k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

19/19 checks healthy over the last 80d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 10d ago via OSV.dev · mcp-retroarch (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars6Stargazers on the source repository.
npm downloads61Package downloads in the last 30 days.
Last commit5d agoMost recent push to the default branch.
Tools exposed17Callable tools this server registers over MCP.
Directory activity6 viewsConfig copies, upvotes, and views on AllMCPs.

How MCP Retroarch works

What dmang-dev/mcp-retroarch MCP server does

dmang-dev/mcp-retroarch MCP server gives an MCP client access to a running RetroArch instance through RetroArch's Network Control Interface (NCI). The bridge supports libretro cores and was verified with NES, SNES, Genesis, N64, GBA, and PS1 cores. It can inspect the loaded game, read configuration values, capture screenshots, control pause and frame advancement, reset the game, display short messages, and manage save states.

Memory access is available through two separate address spaces. The preferred read_memory and write_memory tools use the core's system memory map. The read_ram and write_ram tools use RetroArch's CHEEVOS address space and provide a fallback for cores without a system memory map. Addresses are core- and system-specific, so values from one core should not be reused blindly with another.

How it works

The MCP client communicates with the Node.js bridge over stdio and JSON-RPC. The bridge sends text commands over UDP to RetroArch's NCI, normally at 127.0.0.1:55355. Call retroarch_ping first to test connectivity, then use retroarch_get_status to determine whether a game is loaded and whether it is playing or paused.

Several NCI commands are fire-and-forget. Their responses confirm that a UDP datagram was sent, not that RetroArch applied the command. Follow up with status, memory reads, or a screenshot when the result matters. Frame advancement only works while paused, and pause is exposed as a toggle, so check status before changing it.

Setup and configuration

Install the package globally with npm install -g mcp-retroarch, run it with npx -y mcp-retroarch, or clone the repository and install its dependencies. Node.js 22 or newer is required. RetroArch must be running with Network Commands enabled and its configured port must match the bridge.

Enable the feature in RetroArch's network settings or set network_cmd_enable = "true" and network_cmd_port = "55355" in retroarch.cfg. The dmang-dev/mcp-retroarch MCP server accepts RETROARCH_HOST to change the destination host and RETROARCH_PORT to change the UDP port.

Claude Code can register the command with claude mcp add retroarch --scope user mcp-retroarch. Claude Desktop uses an MCP server entry whose command is mcp-retroarch; restart the application after changing its configuration.

Tools and capabilities

  • Check connectivity and RetroArch version with retroarch_ping.
  • Read run state, system, game basename, and CRC32 with retroarch_get_status.
  • Read exposed configuration parameters with retroarch_get_config.
  • Read or write up to 4096 bytes through either memory API.
  • Toggle pause, advance one frame while paused, or reset the loaded game.
  • Save to or load from the current save slot, load an explicit slot, and move the current slot pointer.
  • Save timestamped PNG screenshots to RetroArch's configured screenshot directory.
  • Display short notification messages in RetroArch's on-screen display.

Memory writes are destructive and disable RetroArch hardcore mode for the session. Save a state first when rollback is needed. Current-slot saves overwrite the selected slot, while explicit-slot loading does not change the slot pointer.

Limitations and notes

The dmang-dev/mcp-retroarch MCP server does not expose game-pad input. RetroArch's separate Remote RetroPad interface is outside this project's scope. Most control calls do not verify execution, and UDP packets can be dropped; retry timed-out requests when appropriate.

System memory maps depend on the loaded core. Mesen and Mupen64Plus-Next were the tested examples with system maps, while several other tested cores required CHEEVOS reads. Screenshot calls do not accept a destination path and cannot confirm that the PNG was written. Save states generally require the same ROM and core version that created them.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about MCP Retroarch

dmang-dev/mcp-retroarch is an MCP server that connects MCP clients to a running RetroArch instance through its UDP Network Control Interface. Its main tools cover connectivity and status checks, configuration reads, memory reads and writes, save-state loading and saving, screenshots, pause, frame advance, reset, slot control, and on-screen messages.

Install it with `npm install -g mcp-retroarch` or run it without a global install using `npx -y mcp-retroarch`. Node.js 22 or newer is required. You can also clone the repository, run `npm install`, and start the local package.

Enable RetroArch Network Commands and use the same UDP port on both sides. The default destination is `127.0.0.1:55355`; configure `network_cmd_enable = "true"` and `network_cmd_port = "55355"`, then call `retroarch_ping` to verify connectivity.

Yes, dmang-dev/mcp-retroarch works with Claude Desktop through a stdio MCP configuration. Add an `mcpServers` entry whose command is `mcp-retroarch`, then restart Claude Desktop.

No, dmang-dev/mcp-retroarch does not provide game-pad input. RetroArch exposes Remote RetroPad through a separate UDP interface, but using it requires a specific core and is outside this server's scope.

Related MCP servers

All in Gaming All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMCP Retroarch AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/dmang-dev-mcp-retroarch?style=directory)](https://allmcps.com/mcp/dmang-dev-mcp-retroarch)
HTML Embed
<a href="https://allmcps.com/mcp/dmang-dev-mcp-retroarch"><img src="https://allmcps.com/api/badge/dmang-dev-mcp-retroarch?style=directory" alt="MCP Retroarch on AllMCPs" /></a>