Opal Emu MCP
An MCP server that lets LLM agents autonomously play retro games by driving a real, unmodified OpalEmu (EmulatorJS) page in a Playwright-controlled browser.
list_roms — list recognized ROM files in the configured local ROM directory (names, likely systems, sizes).
load_rom — boot a game by name from the library, or by Base64 + fileName; returns a first screenshot. Replaces the current game and its unsaved progress.
reset_emulator — hard-reset the loaded game and get a screenshot.
get_current_screen — fetch the last captured frame as PNG without advancing the game.
control_emulator — press or release a controller button (a, b, up, start, l2, etc.), optionally for players 0–3; hold directions across skip_frames via state "down"/"up".
skip_frames — advance at least N core frames, then pause and return a screenshot with the actual frame count.
Optional MCP Apps viewer — clients that support it can render a live interactive control surface backed by the same tools.
The emulator auto-pauses when no tool call is in flight, and all tools except list_roms are registered as MCP Apps tools.
Plays Sega games through the OpalEmu retro emulator, with tools to list and load Sega ROMs, control the controller, capture screenshots, and advance frames in Sega console games.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Opal Emu MCP Load the first available ROM and show me the screen."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that lets LLM agents (Claude, GPT, etc.) autonomously play retro games, by wrapping OpalEmu, a browser-based, EmulatorJS-powered retro emulator supporting 18 systems, with a Node.js bridge.
This project does not modify OpalEmu. It drives a real, unmodified OpalEmu page in a Playwright-controlled browser and exposes it to agents as 6 MCP tools, plus (if the client supports it) a live, interactive MCP Apps viewer.
Credit
All emulation is OpalEmu (source) running EmulatorJS cores. This project only adds the MCP bridge around it; it contributes no emulation code of its own.
Related MCP server: MCP GameBoy Server
License
AGPL-3.0, the same license as OpalEmu (see LICENSE).
Architecture
LLM Agent (Claude, GPT, ...)
│ MCP protocol (stdio)
▼
Node.js MCP server (this project)
│ │
│ WebSocket │ HTML resource (MCP Apps, optional)
▼ ▼
Playwright-controlled Chromium MCP client's own sandboxed iframe
│ runs the real OpalEmu page (client/mcp-app.ts, a *separate*
│ (served by this project's browser context; talks back to this
│ own Express server) server's tools via the App Bridge,
▼ never touches the emulator directly)
window.EJS_emulator
(EmulatorJS instance, the game
actually runs here)Two independent browser contexts are involved, and it's worth being explicit about why:
The Playwright tab (
client/agent.tsinjected into it) is where the game actually runs. It driveswindow.EJS_emulatordirectly and is the only place OpalEmu's real, stateful emulator instance exists.The MCP Apps viewer (
client/mcp-app.ts), if the connecting MCP client supports it, renders in the client's own sandboxed iframe, a completely different, unrelated browser context. It never touches the emulator directly; every button press or screenshot request goes throughApp.callServerTool(), which the host proxies to this server's real tools, the same tools the LLM calls. It's a control surface, not a second embed of the OpalEmu page (embedding the raw page there would boot a second, disconnected, unloaded emulator instance).
Auto-pause
The emulator is paused whenever no tool call is in flight. A button press resumes it briefly; skip_frames runs until at least the requested number of core frames have advanced and reports the measured count. Frame polling can overshoot the target. The emulator pauses again before returning a screenshot, so it does not keep running while an agent is thinking.
Tools
Tool | Description |
| Lists ROM files available on the server (from |
| Loads a ROM by |
| Hard-resets the current game. |
| Returns the last captured frame as a PNG, without advancing the game. |
| Presses or releases a button ( |
| Advances until at least the requested number of core frames has elapsed, then reports the actual count. |
All tools except list_roms are also registered as MCP Apps app tools, so a supporting client can render the live viewer regardless of which one is called first.
Setup
Prerequisites:
Node.js 20+
A built checkout of OpalEmu. By default this project looks for it as a sibling directory (
../OpalEmu/dist); use--opalemu-dist <path>for any other layout. It only ever reads from there, never writes.
# 1. Build OpalEmu itself (the emulator this wraps)
git clone https://github.com/thevalmarch/opalemu ../OpalEmu
cd ../OpalEmu && npm install && npm run build && cd -
# 2. Build this project
npm ci
npx playwright install chromium
npm run buildIf OpalEmu's build isn't found, the server says so explicitly at startup, including the path it looked in.
ROMs
No ROMs are included, and none are downloaded. You supply your own game files, which you should already legally own. Drop them into roms/ (or point elsewhere with --roms-dir <path>) and list_roms will pick up anything with a recognized extension. Nothing in roms/ is committed to git.
Local ROM files larger than 128 MiB are rejected before loading. Direct romBase64 input is limited to 6 MiB decoded so its Base64 and JSON-RPC message fit below the MCP SDK's default 10 MiB stdio limit. Symlinks in the ROM directory are not listed or loaded. Large disc images may need a future streaming path; this release keeps ROM transfer bounded in memory.
Run standalone
npm start # headed browser by default, so you can watch it play
npm start -- --headless # for CI / headless environmentsCLI flags (all optional): --opalemu-dist <path>, --roms-dir <path>, --playwright-profile-dir <path>, --http-port <port> (default 4173), --ws-port <port> (default 4174), --headless. The browser profile defaults to .playwright-profile/ in this checkout.
The HTTP and WebSocket listeners bind to 127.0.0.1. The Playwright browser receives a fresh bridge token at startup. The token is not served by the HTTP page and is not intended for other clients. Do not expose these ports through a proxy or port forward.
Connect to Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"opalemu": {
"command": "node",
"args": ["/absolute/path/to/opalemu-mcp/dist/index.js"]
}
}
}Use absolute paths: Claude Desktop spawns MCP servers without a working directory set.
Compatibility with OpalEmu
Originally tested against OpalEmu commit 776874a, whose package version was 1.1.0. The published v1.1.0 tag is the following commit, 800755a. The v1.1.0 hardening tests also passed with a clean local OpalEmu v1.2.3 checkout at 3df680cd11b40f4590fb64c879e14ea253d5a0c1.
OpalEmu and this project are separate repos with independent versions on purpose: different concerns, different release cadences. In practice, most of what this project depends on isn't OpalEmu-specific at all: button indices, frame counting, screenshot capture, and gameManager.restart() all come from EmulatorJS's stable CDN bundle, a third-party dependency OpalEmu itself just configures. OpalEmu releases mostly don't touch any of that.
The coupling that is real, and worth knowing about before bumping the sibling checkout:
dist/index.html's structure.src/http/static.tsinjectsagent.jswith a literal</body>string-replace. Breaks if OpalEmu's build output changes shape.The
drop-event loading contract.load_romworks by dispatching a synthetic drag-drop event that OpalEmu'suseDragDrop.tslistens for onwindow. Breaks if OpalEmu changes how files get loaded (e.g. drops the drag-drop path in favor of file-input-only).The extension→system list in
src/roms/store.ts. A small local discovery list determines whatlist_romsandload_rom({name})can find. OpalEmu's in-page detection still chooses the actual system. When OpalEmu adds formats, local discovery must be reviewed too.COOP/COEP headers. Mirrored from OpalEmu's own vite/vercel config. Breaks threaded cores (n64, psx, etc.) if OpalEmu's requirements change.
When you update the OpalEmu checkout: rerun npm run test:e2e and npm run test:mcp against it (they boot a real OpalEmu build and exercise the full tool path), then bump the version line above if they pass.
Development
npm run dev # run from source via tsx, no build step
npm run test:e2e # scripted check against a real ROM, no LLM/MCP client needed
npm run test:mcp # spawns the real server and talks real MCP stdio JSON-RPC to it
npm run test:mcp-app # verifies the MCP Apps ui:// resource is registered and well-formed
npm run test:security # network, bridge, and ROM safety regression tests
npm run test:browser # boots the local OpalEmu build and checks the authenticated browser bridgetest:e2e and test:mcp need a ROM in roms/; they use whichever one they find first. test:mcp-app checks the UI resource without a ROM. Build first with npm run build before running test:mcp-app, since it spawns the compiled server. test:security does not need a ROM or browser. test:browser needs a built OpalEmu checkout and Playwright Chromium, but no ROM.
The emulator and MCP smoke scripts accept the server's --http-port and --ws-port flags. The two MCP smoke tests default to 4193/4194 so they do not collide with a running instance; pass the flags explicitly if you need something else:
npm run test:mcp -- --http-port 5000 --ws-port 5001Known limitations
Ambiguous disc formats.
.bin,.iso, or.chdfiles that OpalEmu can't confidently identify (e.g. it can't tell PSX from Sega CD) normally prompt the user with a picker dialog. There's no automated path through that dialog here, soload_romwill time out on such a file. Unambiguous formats (cartridge-based systems, clearly-identified discs) are unaffected.First load per system downloads a core. EmulatorJS cores (5-30MB) download from
cdn.emulatorjs.orgon first use per system;load_romaccounts for this with a generous timeout, and a persistent browser profile (.playwright-profile/) means it only happens once.Stale browser profile data. Cached assets in an older profile may prevent a game from booting after an OpalEmu or EmulatorJS update. Use
--playwright-profile-dir <new-path>to try a fresh profile without deleting the old one.MCP client deadlines. A first
load_rommay need up to 100 seconds, while some MCP clients default to a shorter tool-call deadline. Increase the client's timeout for cold core downloads if it supports that setting.One browser tab, one game at a time. A second
load_romcall replaces the current session; there's no multi-instance support.Frame targets are approximate.
skip_framesmeasures core frames after each display callback and may advance beyond the requested count. Its result states the actual count; it fails if the target is not reached before timeout.EmulatorJS assets are controlled by OpalEmu. The separate OpalEmu checkout currently references the floating
stable/dataCDN path. This project cannot pin its loader and cores without changing OpalEmu or rewriting its built assets. Review that upstream dependency before deployments that require reproducible emulator assets.
Security
See SECURITY.md for private vulnerability reporting guidance. The local HTTP and WebSocket ports are intended only for the Playwright browser started by this process.
Available Tools
6 toolscontrol_emulatorPress or release a buttonADestructive
Presses or releases a controller button. The emulator briefly resumes just long enough for the input to register, then pauses again and returns a PNG screenshot. This advances the game and may affect progress. To hold a direction across skip_frames calls, send state="down" once and state="up" later.
Inputs: state (required), button (required), player.
get_current_screenGet current screenARead-onlyIdempotent
Returns the last captured emulator frame as a PNG image without advancing the game. Fails if no game is loaded.
Inputs: no named parameters.
list_romsList ROMsARead-onlyIdempotent
Lists recognized ROM files in the configured local ROM directory. Returns full filenames, names, likely systems, and sizes. Use a full filename with load_rom; a unique name without its extension also works. Recognition does not guarantee a game will boot.
Inputs: no named parameters.
load_romLoad ROMADestructive
Loads a ROM into the emulator and starts the game, paused, ready for the next tool call. Provide either "name" (from list_roms) or "romBase64" + "fileName" for a ROM not in the library. Returns the first PNG screenshot once the game has booted. Replaces the current game and its unsaved progress. Local ROM files are limited to 128 MiB; direct Base64 ROMs are limited to 6 MiB decoded. Some disc images need multiple files or manual system selection and cannot load through this tool. First use of a system may download a core and can take up to 100 seconds; MCP clients with shorter call deadlines may time out.
Inputs: name, fileName, romBase64.
reset_emulatorReset emulatorADestructive
Hard-resets the loaded game and returns a PNG screenshot. Unsaved game progress may be lost. Fails if no game is loaded.
Inputs: no named parameters.
skip_framesSkip framesADestructive
Runs until at least the requested number of core frames have advanced, then pauses and returns a PNG screenshot with the actual frame count. Frame polling can overshoot the target. Long waits may use fast-forward and fail on timeout.
Inputs: count (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a clearly distinct purpose: listing ROMs, loading, resetting, capturing the current screen, sending controller input, and advancing frames. The three tools that return screenshots (get_current_screen, control_emulator, skip_frames) are differentiated by whether they advance the game, and the descriptions make these boundaries explicit.
All tool names follow a consistent snake_case verb_noun pattern: list_roms, load_rom, reset_emulator, get_current_screen, control_emulator, skip_frames. There are no mixed conventions or vague standalone verbs.
Six tools is well-scoped for an emulator control server. Each tool earns its place, covering discovery, loading, reset, screen capture, input, and frame advancement without redundancy.
The core emulation loop is covered, but save/load state operations are absent, meaning agents cannot preserve progress before risky actions or reset. An explicit stop/unload tool and system selection for problematic disc images are also missing, creating notable gaps.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for building and testing AI agents with multi-model experimentation and insights.
Related MCP Servers
- AlicenseDqualityDmaintenanceAn MCP server that enables LLMs to 'see' what's happening in browser-based games and applications through vectorized canvas visualization and debug information.14 npm54MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server that enables LLMs to interact with a GameBoy emulator, providing tools for controlling the GameBoy, loading ROMs, and retrieving screen frames.1338MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that allows LLMs to interact with Game Boy games through PyBoy emulation, providing capabilities to load ROMs, control games, capture screens, save/load states, and maintain game knowledge.1MIT
- AlicenseAqualityBmaintenanceAn MCP server for the Pyxel retro game engine that enables AI models to autonomously run, verify, and iterate on retro game programs. It includes tools for visual verification through screenshots, sprite and layout analysis, and audio rendering.8168 PyPI32MIT