mame-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| MAME_CWD | No | Working directory for generated scripts/logs and MAME state. | |
| MAME_EXE | No | MAME executable or command on PATH. | mame |
| MAME_SYSTEM | No | Default machine short name, e.g. driver_short_name. | |
| MAME_ROMPATH | No | ROM search path. | |
| MAME_WORKDIR | No | Generated Lua, logs, nvram, cfg, etc. | .mame_mcp |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| pingA | Echo back an optional payload. Use to verify the MCP bridge is alive. |
| config_checkB | Resolve MAME env/config paths and report which required pieces exist. |
| audit_romsetA | Run |
| get_ioportsA | Boot a machine briefly and list MAME Lua IO-port fields for input injection. |
| trace_memory_accessB | Install Lua read/write taps over CPU address ranges and log deduped accesses. |
| trace_cchip_supermanB | Superman helper: trace $900000-$900FFF C-Chip accesses and report $900803 status verdict. |
| run_lua_scriptB | Run a caller-supplied MAME Lua autoboot script headlessly. |
| run_lua_inlineA | Run caller-supplied MAME Lua source (string, not a path) headlessly; optionally read back an artifact file. |
| capture_leaf_ioB | Golden-vector capture for a pure leaf that transforms one memory word/byte in place (RNG/counter/accumulator). Injects inputs via taps, records output + regs + CCR. Independent oracle for the transpiler differential harness. |
| mame_launchA | Launch a PERSISTENT live MAME (headless + bridge) and keep it running across tool calls. Required before any other mame_* live tool. |
| mame_session_stopB | Terminate the live MAME session. |
| mame_session_statusB | Live session status (system, frame, paused). |
| mame_pauseA | Pause the live machine (state stays readable). |
| mame_resumeB | Resume the live machine. |
| mame_run_framesA | Run N frames then pause; returns the frame number. |
| mame_load_stateA | Load a MAME save state by name (needs stateDirectory). Apply with a run_frames after. |
| mame_save_stateB | Save a MAME save state by name. |
| mame_get_regsA | Read all CPU state registers (D0-D7,A0-A7,PC,SR,USP,...). |
| mame_set_regD | Set one CPU register. |
| mame_read_memoryC | Read a memory block (hex) from a device's program space. |
| mame_write_memoryB | Write a hex block to a device's program space. |
| mame_send_inputB | Set an ioport field value (e.g. 'Coin 1', 'P1 Right'). |
| mame_capture_game_tickB | Run to the Nth GAME_TICK ($3A92) and snapshot regs + a memory region AT the prologue read (lockstep regsA/wramA primitive; entry a7 = SP+60). |
| mame_drive_to_gameplayA | BOOT-AWARE drive to a running game: wait for the $0818 idle (boot done), inject clean coin/start EDGES, confirm GAME_TICK. Replay-robust where a fixed-frame .inp desyncs (the C-Chip boot handshake isn't bit-reproducible). |
| mame_exec_lua_liveB | Run Lua on the live machine (vars M/machine = manager.machine); returns its value. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 25 tools
Multiple tools have overlapping purposes: three different Lua execution tools (mame_exec_lua_live, run_lua_script, run_lua_inline), two tracing tools (trace_memory_access, trace_cchip_superman), and two gameplay automation tools (mame_drive_to_gameplay, mame_capture_game_tick) that are easy to confuse. Descriptions help distinguish them, but an agent would likely struggle to pick the right one without deep domain knowledge.
Tool names are mixed: some use the mame_ prefix (mame_launch, mame_get_regs), while others do not (ping, audit_romset, trace_memory_access). Verb patterns also vary (run_lua_script vs mame_exec_lua_live, capture_leaf_io vs mame_capture_game_tick). While all use snake_case, the inconsistent prefix and verb choices make the set feel disjointed.
25 tools is at the high end of the acceptable range and feels heavy for the server's purpose. Many tools could be consolidated (e.g., Lua execution variants, tracing helpers), which would reduce the surface area without losing functionality. Still, the complexity of MAME emulation and debugging justifies a larger toolset than typical servers.
The server covers a broad range of MAME operations: session lifecycle, memory/register access, input injection, Lua scripting, state save/load, tracing, and gameplay capture. Minor gaps exist, such as no tool to list save states or enumerate devices, but these are workable. The core workflows for reverse engineering and deterministic gameplay are well supported.