pymgba-mcp

This is a vibecoded Python-based MCP (Model Context Protocol) server for the mGBA Game Boy/GBA emulator using native Python bindings. It interacts with mGBA through its native Python bindings, allowing not only to take screenshots but also to control the emulator, read and write memory, add breakpoints, and more - meant for vibe coding GB homebrew games.

It also ships as a Nix flake, to build mGBA and the Python bindings all together for a portable, easy to reproduce setup.

Features

• Native Python bindings: Uses mGBA's built-in Python API instead of spawning external processes
• Full emulator control: Run frames, step instructions, pause/unpause
• Memory access: Read/write memory at any address
• Button input: Press and hold Game Boy buttons
• Screenshots: Capture the screen at any time
• Save states: Save and load emulator state
• Debugging: Set breakpoints, read CPU registers, step through code
• OAM inspection: View sprite data

Tools

Tool	Description
run_rom	Load and run a ROM for N frames, returns screenshot
step_frame	Run a single frame (or N frames)
press_button	Press a button (A, B, Start, Select, D-pad)
read_memory	Read bytes from a memory address
write_memory	Write bytes to a memory address
read_memory_range	Read a contiguous range of bytes
take_screenshot	Capture the current screen
save_state	Save emulator state
load_state	Load emulator state
get_registers	Get CPU register values
dump_oam	Dump sprite (OAM) data
reset	Reset the emulator

Usage with your favorite vibe coding tool

Install Nix: https://nixos.org/download.html, and add to your MCP settings:

{
  "mcpServers": {
    "pymgba": {
      "command": "nix",
      "args": ["run", "github:zenitraM/pymgba-mcp"],
    }
  }
}

Running with Nix

Install Nix: https://nixos.org/download.html, clone this repo:

nix run .

Or directly from GitHub:

nix run github:zenitraM/pymgba-mcp