mgba_read_memory
Read memory values from specific addresses in Game Boy, Game Boy Color, or Game Boy Advance games after running for a set number of frames to analyze game state or automate testing.
Instructions
Read memory at specified addresses after running for some frames
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| rom_path | Yes | Path to the ROM file | |
| addresses | Yes | List of memory addresses to read (as integers, e.g., [0xC200, 0xFFBF]) | |
| savestate_path | No | Optional savestate to load | |
| frames | No | Frames to run before reading (default: 60) |
Implementation Reference
- src/mgba_mcp/emulator.py:123-154 (handler)Implements the mgba_read_memory tool by generating and executing a Lua script that reads memory values at given addresses after running the specified number of frames using mGBA headless mode.def read_memory( self, rom_path: str, addresses: list[int], savestate_path: Optional[str] = None, frames_before_read: int = 60, ) -> EmulatorResult: """Read memory at specified addresses.""" addr_list = ", ".join(f"0x{a:04X}" for a in addresses) lua_script = f""" local frame = 0 local addresses = {{{addr_list}}} callbacks:add("frame", function() frame = frame + 1 if frame >= {frames_before_read} then local f = io.open("output.json", "w") if f then f:write('{{') for i, addr in ipairs(addresses) do if i > 1 then f:write(',') end f:write(string.format('"0x%04X":%d', addr, emu:read8(addr))) end f:write('}}') f:close() end emu:screenshot("screenshot.png") emu:quit() end end) """ return self._run_with_lua(rom_path, lua_script, savestate_path)
- src/mgba_mcp/server.py:60-82 (schema)Defines the input schema for the mgba_read_memory tool, specifying parameters like rom_path, addresses (required), savestate_path, and frames.inputSchema={ "type": "object", "properties": { "rom_path": { "type": "string", "description": "Path to the ROM file", }, "addresses": { "type": "array", "items": {"type": "integer"}, "description": "List of memory addresses to read (as integers, e.g., [0xC200, 0xFFBF])", }, "savestate_path": { "type": "string", "description": "Optional savestate to load", }, "frames": { "type": "integer", "description": "Frames to run before reading (default: 60)", "default": 60, }, }, "required": ["rom_path", "addresses"],
- src/mgba_mcp/server.py:57-84 (registration)Registers the mgba_read_memory tool in the MCP server's list_tools() function, including name, description, and input schema.Tool( name="mgba_read_memory", description="Read memory at specified addresses after running for some frames", inputSchema={ "type": "object", "properties": { "rom_path": { "type": "string", "description": "Path to the ROM file", }, "addresses": { "type": "array", "items": {"type": "integer"}, "description": "List of memory addresses to read (as integers, e.g., [0xC200, 0xFFBF])", }, "savestate_path": { "type": "string", "description": "Optional savestate to load", }, "frames": { "type": "integer", "description": "Frames to run before reading (default: 60)", "default": 60, }, }, "required": ["rom_path", "addresses"], }, ),
- src/mgba_mcp/server.py:232-253 (handler)Dispatches the mgba_read_memory tool call in the MCP server's call_tool handler, invoking the emulator's read_memory method and formatting the results for output.elif name == "mgba_read_memory": result = emu.read_memory( rom_path=arguments["rom_path"], addresses=arguments["addresses"], savestate_path=arguments.get("savestate_path"), frames_before_read=arguments.get("frames", 60), ) if result.success and result.data: # Format memory as hex dump lines = ["Memory dump:"] for addr_str, value in result.data.items(): lines.append(f" {addr_str}: 0x{value:02X} ({value})") result_content.append(TextContent(type="text", text="\n".join(lines))) if result.screenshot: result_content.append(ImageContent( type="image", data=base64.b64encode(result.screenshot).decode(), mimeType="image/png", )) else: result_content.append(TextContent(type="text", text=f"Error: {result.error}"))