mesen-for-ai
This server is an MCP bridge that lets AI agents drive Mesen headlessly for console reverse engineering and game conversion work, exposing debugger-facing Lua functionality as MCP tools over stdio.
Session management: load ROMs (including ZIPs), inspect session info, reset, and shut down sessions.
Emulation control: step a specified number of frames, optionally resetting first, and check run status.
Input control: set or get named controller button latches, applied at Mesen's safe
inputPolledcallback.Video export: write the current rendered frame as a binary P6 RGB image.
CPU inspection: read/write CPU memory and inspect registers, with optional CPU type and state.
Watches: create, list, and delete watchpoints on memory regions/addresses to observe accesses.
Breakpoints: create, list, and delete breakpoints on memory/address conditions.
Code/Data Logger (CDL): start/stop coverage windows, read decoded CDL bytes by offset/length, and export CDL maps with range summaries and byte counts.
Tracing: start, stop, and list CPU instruction traces.
Supported systems: SNES, NES, PC Engine, and Game Boy Advance, with CDL coverage for their main ROM/CHR regions.
Deterministic evidence runs: supports reproducible RAM dumps and controlled reset-plus-frames operations for reliable reverse-engineering experiments.
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., "@mesen-for-ai Load the ROM, step 60 frames, and dump the CPU registers."
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.
mesen-for-ai
mesen-for-ai is an MCP server that lets AI agents drive Mesen headlessly for
console reverse engineering and game conversion work.
It does not port or vendor Mesen. It launches an existing Mesen/MesenCE binary,
runs bridge.lua inside the emulator, and exposes the debugger-facing Lua API
over MCP JSON-RPC on stdio.
If you are an LLM, read this first: AGENTS.md.
Supported Systems
Use this project for Mesen systems where the required debugger surface is available:
SNES / Super Nintendo
NES / Famicom
PC Engine / TurboGrafx-16, including CD-ROM² cue sheets
Game Boy Advance
The Code/Data Logger is available for SNES PRG ROM, NES PRG/CHR ROM, PC Engine PRG ROM, and GBA PRG ROM. Mesen emulates more systems, but this project does not promise CDL coverage for Master System, Game Boy, or WonderSwan because Mesen does not register those CDL loggers.
Related MCP server: mcp-mgba
Requirements
Python 3.11 or newer.
xvfb-runon Linux for headless Mesen execution.A Mesen or MesenCE build with
--testrunnersupport and Lua socket support.Set
MESEN_BINto the Mesen executable you want to use.
Example:
export MESEN_BIN=/path/to/MesenThe local wrapper has a development default for MESEN_BIN, but public use
should set the variable explicitly.
PC Engine CD sessions also require a user-supplied System Card 3 image. The runner copies it into the isolated session home and Mesen verifies its hash:
export MESEN_PCECD_FIRMWARE=/path/to/syscard3.pceRun the MCP Daemon
From a checkout:
PYTHONPATH=src python3 -m mesen_mcp.daemonThe daemon speaks MCP-style JSON-RPC 2.0 over its own stdio. Mesen stdout and
stderr are not part of the MCP protocol; Mesen talks to the daemon through a
per-session TCP socket opened by bridge.lua.
Headless Runner
You can run a Lua testrunner script directly:
MESEN_BIN=/path/to/Mesen ./scripts/run_headless.sh <rom> <script.lua>The runner creates an isolated Mesen home and writes deterministic settings:
Lua IO/OS access enabled.
Lua network access enabled for the socket bridge.
deterministic RAM power-on state for SNES, NES, PC Engine, GBA, and Game Boy.
a standard two-button controller on PC Engine port 1.
NES mapper and CPU/PPU alignment randomization disabled.
Set MESEN_PCE_TURBOTAP=1 when a PC Engine verification needs two players.
The isolated session then uses a TurboTap with standard two-button controllers
on subports 0 and 1; input.set addresses them with port=0, subport=0/1.
MesenCE 2.2.1 also needs patches/mesence-lua-input-subport.patch: its
LuaApi::SetInput first requires three parameters and then grows the Lua stack
to four, shifting the values read by LuaCallHelper. Removing that second
stack adjustment makes the requested TurboTap subport reach the input manager.
For a deterministic RAM smoke test:
MESEN_BIN=/path/to/Mesen MESEN_MCP_FRAMES=60 MESEN_MCP_DUMP_PATH=/tmp/ram-a.bin \
./scripts/run_headless.sh /path/to/game.sfc scripts/dump_ram.lua
MESEN_BIN=/path/to/Mesen MESEN_MCP_FRAMES=60 MESEN_MCP_DUMP_PATH=/tmp/ram-b.bin \
./scripts/run_headless.sh /path/to/game.sfc scripts/dump_ram.lua
cmp /tmp/ram-a.bin /tmp/ram-b.binMCP Tools
Implemented tools:
session.load_rom,session.info,session.reset,session.shutdownrun.step_frames,run.statusinput.set,input.getvideo.export_framecpu.registers,cpu.read_memory,cpu.write_memoryconsole.statefor the held machine's complete serialized scalar state, including NES PPUVideoRamAddr,TmpVideoRamAddr,ScrollX, andWriteTogglewatch.create,watch.list,watch.deletebreakpoint.create,breakpoint.list,breakpoint.deletecdl.start,cdl.stop,cdl.get,cdl.exporttrace.start,trace.stop,trace.list
session.load_rom accepts normal ROM files and ZIP archives. For ZIPs, the
daemon extracts the single supported ROM member into the session temporary
directory, launches Mesen against that extracted file, and removes it on
session.shutdown.
Mesen accepts PC Engine CD media as a .cue plus its referenced track files.
For those sessions, pceCdromRam exposes the CD unit RAM and pceCardRam
exposes the 192 KiB Super CD-ROM² RAM supplied by System Card 3, in addition to
the usual pceMemory, pceWorkRam, and pcePrgRom aliases.
pceArcadeCardRam separately exposes the 2 MiB Arcade Card expansion RAM when
that hardware is active. pceAdpcmRam, pceVideoRam, pceSpriteRam, and
pcePaletteRam expose the remaining asset-bearing memories needed to verify
audio and graphics extraction. Disc images and System Card firmware remain
private inputs and are never copied into this repository.
Start deterministic PC Engine CD evidence from a new session and advance with
reset=false. In the source-built MesenCE version validated here, calling
emu.reset() from the bridge after a cue sheet has started closes the testrunner
instead of returning a frame response. A fresh isolated session supplies the
cold-boot boundary without that reset call.
PC Engine CD READ(6) compatibility patch
MesenCE commit 20ba206cef5ba207c21203176d02cb9f43dda9fb treats a zero
READ(6) transfer-length byte as an empty request. SCSI READ(6) defines that byte
as 256 sectors, and commercial PC Engine CD software can depend on it. Apply
patches/mesence-pce-read6-zero-length.patch to that revision before building:
git apply /path/to/mesen-for-ai/patches/mesence-pce-read6-zero-length.patch
git apply /path/to/mesen-for-ai/patches/mesence-lua-input-subport.patch
make core -j4
make uiThe patch widens the saved sector counter to 16 bits and maps command byte zero
to 0x100. It was validated with the Japanese PC Engine CD release of World
Heroes 2: command 08 00 22 78 00 00 transfers sectors 8824 through 9079 and
allows the original post-versus loader to reach CPU $C15B. No game bytes or
firmware are included here.
For deterministic evidence runs, call run.step_frames with reset=true. That
makes reset plus N frames one bridge operation and avoids variable frames
between separate MCP calls. A newly loaded ROM is held before its first frame
starts until that explicit run request, so watches and CDL can be armed without
recording an uncontrolled pre-reset interval.
input.set latches named controller buttons and applies them from Mesen's
inputPolled callback, which is the only safe point for scripted input. Change
the latch while held at a frame boundary, then advance the intended number of
frames. video.export_frame writes the held rendered frame as binary P6 RGB.
Code/Data Logger Semantics
Mesen's Lua API exposes getCdlData; it does not expose a logger on/off switch.
cdl.start and cdl.stop are MCP-side window markers only. Collection is
continuous inside Mesen.
The Lua getCdlData table is zero-indexed even though ordinary Lua arrays are
usually one-indexed. The bridge preserves physical ROM offset zero as JSON
element zero; do not add an index adjustment in callers.
cdl.export returns coveredBytes and memorySize. Equality means the exported
map has one decoded record for every byte in that ROM region. It does not mean
the run executed or read the whole ROM.
The evidence that CDL is live is growth in codeBytes, dataBytes, and
summaryRanges when a deterministic run is driven for longer or through more
gameplay.
NES CHR is the platform-specific exception to the generic flag names. Mesen's
source defines bit 0x01 as NesChrDrawn for CHR ROM, not CPU Code.
Inline/exported CHR records therefore expose drawn, summaries classify those
ranges as drawn, and export counts report drawnBytes; codeBytes and
dataBytes remain zero for CHR.
Skills
The repo ships Codex/Codex-compatible skills in skills/:
skills/mesen-emulator- load ROMs, manage session handles, step frames, read/write memory, and inspect CPU registers.skills/mesen-debug- answer debugging questions with watches, breakpoints, traces, registers, and memory inspection.skills/mesen-codedata- export and interpret Mesen Code/Data Logger maps.
Install them by symlinking or copying the skill directories into your agent's
skill directory. If the skills are installed outside this checkout, set
MESEN_FOR_AI_REPO to the checkout root so scripts/mesen_client.py can find
the daemon.
Validation
Unit and static smoke tests:
python3 -m py_compile src/mesen_mcp/*.py scripts/test_mcpd.py
PYTHONPATH=src python3 -m unittest discover -s tests -vReal emulator validation requires a private test ROM supplied by the user:
MESEN_BIN=/path/to/Mesen PYTHONPATH=src scripts/test_mcpd.py --rom /path/to/test-rom.zip --frames 60Do not commit, upload, or redistribute ROM, BIOS, firmware, disc-image, or other copyrighted game material.
License
mesen-for-ai is licensed under GPL-3.0-only. See LICENSE.
Mesen itself is an upstream GPL-3.0 emulator and is not vendored in this
repository. The wrapper code in this repository is original, but bridge.lua
runs inside the Mesen process and calls Mesen's Lua API directly. The
conservative licensing position is therefore to publish the wrapper under
GPL-3.0-only as well.
Available Tools
22 toolsbreakpoint.createD
breakpoint.create
Inputs: address (required), session (required), memoryType (required), access, +2 more.
breakpoint.deleteD
breakpoint.delete
Inputs: handle (required), session (required).
breakpoint.listD
breakpoint.list
Inputs: session (required).
cdl.exportC
Export decoded Code/Data Logger bytes and contiguous range summaries for a supported ROM region.
Inputs: path (required), session (required), memoryType.
cdl.getC
Read decoded Code/Data Logger bytes from a supported ROM region.
Inputs: session (required), length, offset, memoryType.
cdl.startB
CDL collection is continuous in Mesen Lua and cannot be turned on or off; this marks the session's intended coverage window.
Inputs: session (required).
cdl.stopA
CDL collection is continuous in Mesen Lua and cannot be turned on or off; this marks the coverage window as no longer active.
Inputs: session (required).
cpu.read_memoryD
cpu.read_memory
Inputs: length (required), address (required), session (required), memoryType (required).
cpu.registersD
cpu.registers
Inputs: session (required), state, cpuType.
cpu.write_memoryD
cpu.write_memory
Inputs: bytes (required), address (required), session (required), memoryType (required).
run.statusD
run.status
Inputs: session (required).
run.step_framesD
run.step_frames
Inputs: frames (required), session (required), reset.
session.infoD
session.info
Inputs: session (required).
session.load_romD
session.load_rom
Inputs: rom (required), timeout, mesen_bin.
session.resetD
session.reset
Inputs: session (required).
session.shutdownD
session.shutdown
Inputs: session (required).
trace.listD
trace.list
Inputs: session (required).
trace.startD
trace.start
Inputs: session (required), cpuType.
trace.stopD
trace.stop
Inputs: handle (required), session (required).
watch.createD
watch.create
Inputs: address (required), session (required), memoryType (required), access, +2 more.
watch.deleteD
watch.delete
Inputs: handle (required), session (required).
watch.listD
watch.list
Inputs: session (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Every tool is namespaced by domain (session, run, cpu, watch, breakpoint, trace, cdl) with a specific action, so there is no ambiguity between them. Even similar list operations are clearly scoped (watch.list vs breakpoint.list vs trace.list).
All tools follow the same `<domain>.<action>` pattern using lowercase snake_case. The action is consistently a verb (load, reset, create, delete, start, stop) or a common noun for getters (info, status, registers), maintaining a uniform and predictable structure.
With 22 tools, this sits in the borderline heavy category (16-25). While each tool has a distinct purpose, the large number could overwhelm an agent, though it may be justified by the broad scope of emulator debugging features.
The set covers session management, CPU/memory access, breakpoints, tracing, and CDL, but lacks essential emulator interactions for AI use such as input injection, video/screen capture, or save/load states. These gaps prevent an agent from fully controlling or observing a game, making the surface significantly incomplete.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to control Unreal E…
MCP server exposing the Backtest360 engine API as tools for AI agents.
Related MCP Servers
- AlicenseAqualityBmaintenanceMCP server for RetroArch via its Network Control Interface. Drive any libretro core — read/write memory, save/load state, screenshot, pause/frame-advance/reset — across NES, SNES, Genesis, N64, GBA, PS1 and more.1726 npm6MIT
- AlicenseAqualityBmaintenanceMCP server for the mGBA Game Boy Advance emulator. Read and write GBA memory, inject button presses, take screenshots, save/load state, and step the emulator through a Lua bridge.1835 npm7MIT
- AlicenseAqualityCmaintenanceMCP server for BizHawk, the multi-system emulator. Drive NES, SNES, GB/GBC/GBA, Genesis, N64, PSX, Saturn and more through one Lua bridge — memory r/w across named domains, joypad input, frame-advance, screenshot, save/load state.2051 npm6MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for the mGBA Game Boy/GBA emulator, enabling full emulator control, memory access, debugging, and screenshot capture through natural language.5MIT