mGBA MCP Server

Instructions

Implementation Reference

• src/mgba_mcp/server.py:340-365 (handler)

  MCP server tool handler for 'mgba_run_lua': invokes emulator.run_lua_script with arguments and formats the result (text output from data/stdout/error, optional screenshot) into MCP content.
  elif name == "mgba_run_lua": result = emu.run_lua_script( rom_path=arguments["rom_path"], script=arguments["script"], savestate_path=arguments.get("savestate_path"), timeout=arguments.get("timeout", 30), ) lines = [] if result.success: lines.append("Lua script executed successfully") if result.data: lines.append(f"Output data: {json.dumps(result.data, indent=2)}") if result.output: lines.append(f"Stdout: {result.output}") else: lines.append(f"Error: {result.error}") 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", ))
• src/mgba_mcp/server.py:177-203 (registration)

  Registers the 'mgba_run_lua' tool with the MCP server in list_tools(), including full input schema definition.
  Tool( name="mgba_run_lua", description="Run a custom Lua script in the emulator. The script can use emu:read8(), emu:write8(), emu:screenshot(), callbacks:add(), etc.", inputSchema={ "type": "object", "properties": { "rom_path": { "type": "string", "description": "Path to the ROM file", }, "script": { "type": "string", "description": "Lua script to execute. Use emu:quit() to exit. Write JSON to 'output.json' for structured data.", }, "savestate_path": { "type": "string", "description": "Optional savestate to load", }, "timeout": { "type": "integer", "description": "Timeout in seconds (default: 30)", "default": 30, }, }, "required": ["rom_path", "script"], }, ),
• src/mgba_mcp/emulator.py:432-440 (helper)

  Emulator method directly called by MCP handler; delegates to internal _run_with_lua for execution.
  def run_lua_script( self, rom_path: str, script: str, savestate_path: Optional[str] = None, timeout: int = 30, ) -> EmulatorResult: """Run a custom Lua script.""" return self._run_with_lua(rom_path, script, savestate_path, timeout)
• src/mgba_mcp/emulator.py:126-253 (helper)

  Core implementation: launches mGBA headless with custom Lua script via subprocess (xvfb-run mgba-qt --script), uses DONE marker file for completion detection, captures screenshot.png and output.json, validates/normalizes PNG, handles timeout/process kill.
  def _run_with_lua( self, rom_path: str, lua_script: str, savestate_path: Optional[str] = None, timeout: int = 30, ) -> EmulatorResult: """Run mGBA with a Lua script and return results. Uses watchdog pattern: polls for DONE marker file, then kills process. """ # Convert paths to absolute (subprocess runs in temp_dir) rom_path = str(Path(rom_path).resolve()) if savestate_path: savestate_path = str(Path(savestate_path).resolve()) # Clean up any previous run done_file = self.temp_dir / "DONE" if done_file.exists(): done_file.unlink() for f in ["screenshot.png", "output.json"]: p = self.temp_dir / f if p.exists(): p.unlink() # Write Lua script to temp file lua_file = self.temp_dir / "script.lua" lua_file.write_text(lua_script) # Build command cmd = [] if self.use_xvfb: cmd.extend(["xvfb-run", "-a"]) cmd.extend([self.mgba_path, rom_path]) if savestate_path: cmd.extend(["-t", savestate_path]) cmd.extend(["--script", str(lua_file), "-l", "0"]) try: # Disable audio to prevent sound leakage in headless mode env = os.environ.copy() env["SDL_AUDIODRIVER"] = "dummy" # Start process in new process group for clean kill proc = subprocess.Popen( cmd, stdout=subprocess.PIPE, stderr=subprocess.PIPE, cwd=str(self.temp_dir), start_new_session=True, env=env, ) # Poll for DONE file or timeout start_time = time.time() poll_interval = 0.1 # 100ms while time.time() - start_time < timeout: # Check if script wrote DONE marker if done_file.exists(): # Give script time to finish writing and flushing files # mGBA screenshot can be slow to flush time.sleep(0.5) # Double-check screenshot file is stable (not still being written) screenshot_path = self.temp_dir / "screenshot.png" if screenshot_path.exists(): size1 = screenshot_path.stat().st_size time.sleep(0.1) size2 = screenshot_path.stat().st_size if size1 != size2: # File still growing, wait more time.sleep(0.5) break # Check if process died if proc.poll() is not None: break time.sleep(poll_interval) # Kill the process (emu:quit() doesn't work reliably) self._kill_process_tree(proc) # Collect output files screenshot_path = self.temp_dir / "screenshot.png" output_path = self.temp_dir / "output.json" screenshot = None if screenshot_path.exists(): screenshot_data = screenshot_path.read_bytes() # Validate and normalize PNG for Claude API compatibility normalized_data, error_msg = validate_and_normalize_png(screenshot_data) if normalized_data: screenshot = normalized_data else: # Log validation failure for debugging import sys print(f"PNG validation failed: {error_msg} (size={len(screenshot_data)})", file=sys.stderr) output_data = None if output_path.exists(): try: output_data = json.loads(output_path.read_text()) except json.JSONDecodeError: pass # Success if we got expected output if screenshot or output_data or done_file.exists(): return EmulatorResult( success=True, screenshot=screenshot, data=output_data, ) return EmulatorResult( success=False, error=f"Emulator timed out after {timeout}s without producing output", ) except Exception as e: return EmulatorResult( success=False, error=str(e), )