mame_mcp

mame_mcp is a Model Context Protocol bridge for MAME-focused reverse engineering. It is aimed at arcade-to-SNES porting work: memory access traces, input injection, ROM audit checks, IO-port discovery, and reproducible headless harnesses.

Stock-MAME compatible — no custom MAME binary required. Two modes, both on stock MAME: the stateless tools drive MAME with generated -autoboot_script Lua sidecars (spawn, run, exit); the live session suite keeps a persistent MAME alive behind a bridge and exposes debugger-style live memory read/write, register access, run/pause, save/load state, and input injection across calls. A deeper MAME source fork is still only needed for the harder stuff (low-overhead instruction-trace ring buffers; device introspection Lua can't reach) — see Fork Roadmap.

Quick Start

python -m pip install -e .

$env:MAME_EXE = "/path/to/mame"      # or leave unset if mame is on PATH

mame-mcp-tools --names
mame-mcp-tools --category trace

Wire it into Codex or another MCP client:

{
  "mcpServers": {
    "mame": {
      "command": "mame-mcp-bridge",
      "env": {
        "MAME_EXE": "/path/to/mame"
      }
    }
  }
}

Restart the MCP client after editing its config.

This repo includes a generic .mcp.json that only starts the bridge. Pass system and rompath in each tool call, or set MAME_SYSTEM and MAME_ROMPATH in your local MCP config for the project you are inspecting.

Related MCP server: mGBA MCP Server

Tools

Two families: stateless one-shot tools (each spawns MAME, does its job, exits) and a live session suite (one persistent MAME kept alive across calls — read/write/run/inject like a debugger). 25 tools total.

Stateless (one-shot)

Live session (persistent MAME, debugger-style)

Call mame_launch first (keeps MAME running across calls); the rest operate on that session.

The MCP responses return JSON text with command lines, log paths, return codes, stderr/stdout tails, and parsed trace summaries where applicable.

Environment

Generic Trace Example

{
  "system": "driver_short_name",
  "rompath": "/path/to/roms",
  "frames": 1800,
  "ranges": [
    { "name": "device_window", "start": 9437184, "end": 9441279 }
  ],
  "trackReads": [
    { "name": "status", "address": 9439234 }
  ],
  "injectPreset": "none",
  "dryRun": true
}

trace_memory_access installs read/write taps over each range, dedupes by (R/W, PC, address, range), optionally counts values read from selected addresses, and writes a human-readable log plus a parsed JSON summary.

Use "dryRun": true to generate the Lua harness without launching MAME.

Superman C-Chip Helper

trace_cchip_superman is a convenience wrapper for the known Superman C-Chip window. It still requires the caller or environment to provide the ROM path.

{
  "rompath": "/path/to/roms",
  "frames": 1800,
  "injectPreset": "none"
}

It expands to a trace_memory_access call over $900000-$900FFF, tracking reads from $900802/$900803 and reporting whether status $01 and $05 were seen.

Fork Roadmap

The stock-MAME Lua layer can cover a lot:

• address read/write taps,

• frame callbacks,

• input-field injection,

• ROM audit and machine metadata,

• screenshots via MAME command-line/video options,

• reproducible generated scripts and logs.

Already delivered without a fork, via the live-session bridge (stock MAME + a persistent process): a long-lived session, debugger-grade live memory reads/writes, register get/set, run/pause, and save/load state (the mame_* tools above).

A true MAME source fork becomes worthwhile only for what Lua/the bridge can't do well:

• instruction trace ring buffers with low overhead,

• tile/sprite/sound device introspection not exposed through Lua,

• screenshot APIs as one-shot MCP calls.

The MCP tool names and response shapes here are intentionally similar to the Mesen MCP bridge so agents can learn one mental model and apply it to both console and arcade sources.