Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mGBA MCP Server dump sprite data from my Pokemon ROM after 60 frames"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP (Model Context Protocol) server for mGBA emulator - enables programmatic control of Game Boy, Game Boy Color, and Game Boy Advance emulation.
Headless execution - Runs via xvfb for automated testing
Screenshot capture - Get PNG screenshots at any frame
Memory reading - Read individual addresses or memory ranges
OAM dumping - Dump all 40 sprite entries with position, tile, flags, and palette
Entity dumping - Read game entity/actor data from WRAM
Custom Lua scripts - Execute arbitrary Lua code in the emulator
Savestate support - Load savestates for reproducible testing
Related MCP server: mcp-mgba
# Install with uv
uv pip install -e .
# Or with pip
pip install -e .Python 3.11+
mGBA (mgba-qt) installed and in PATH
xvfb-run (for headless operation on Linux)
Run a ROM for a specified number of frames and capture a screenshot.
{
"rom_path": "/path/to/game.gb",
"frames": 120,
"savestate_path": "/path/to/save.ss0"
}Read memory at specified addresses.
{
"rom_path": "/path/to/game.gb",
"addresses": [49664, 65471],
"frames": 60
}Read a contiguous range of memory.
{
"rom_path": "/path/to/game.gb",
"start_address": 49664,
"length": 256,
"frames": 60
}Dump OAM (Object Attribute Memory) sprite data.
{
"rom_path": "/path/to/game.gb",
"savestate_path": "/path/to/save.ss0",
"frames": 60
}Dump entity/actor data from WRAM.
{
"rom_path": "/path/to/game.gb",
"entity_base": 49664,
"entity_size": 24,
"entity_count": 10,
"frames": 60
}Execute a custom Lua script in the emulator.
{
"rom_path": "/path/to/game.gb",
"script": "callbacks:add('frame', function() if emu:currentFrame() > 60 then emu:screenshot('screenshot.png'); emu:quit() end end)",
"timeout": 30
}Add to your Claude Code MCP settings:
{
"mcpServers": {
"mgba": {
"command": "uv",
"args": ["run", "--directory", "/path/to/mgba-mcp", "mgba-mcp"]
}
}
}Once configured, Claude Code can use commands like:
Use mgba_dump_oam to check sprite palettes in rom/working/penta_dragon_dx_FIXED.gbUse mgba_read_range to dump entity data at 0xC200 for 256 bytesCommon memory regions:
0x8000-0x9FFF - VRAM (tile data)
0xC000-0xDFFF - WRAM (work RAM)
0xFE00-0xFE9F - OAM (sprite attributes)
0xFF00-0xFF7F - I/O registers
0xFF80-0xFFFE - HRAM (high RAM)
MIT
Dump entity/actor data from WRAM - useful for analyzing game objects
| Name | Required | Description | Default |
|---|---|---|---|
| rom_path | Yes | Path to the ROM file | |
| entity_base | No | Base address of entity array (default: 0xC200) | |
| entity_size | No | Size of each entity in bytes (default: 24) | |
| entity_count | No | Number of entities to dump (default: 10) | |
| savestate_path | No | Optional savestate to load | |
| frames | No | Frames to run before dumping (default: 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions dumping data from WRAM, which implies a read operation, but doesn't clarify if this is safe (non-destructive), requires specific game states, or has side effects like loading a savestate. The description lacks details on output format, error handling, or performance considerations, which are critical for a tool with multiple parameters and no output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and front-loaded with the core purpose in the first clause. It consists of two short sentences that are efficient and avoid redundancy. However, it could be slightly more structured by explicitly stating the tool's role relative to siblings or including key behavioral notes, but it earns a high score for being direct and waste-free.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, no annotations, no output schema), the description is incomplete. It doesn't cover behavioral aspects like safety, output format, or error conditions, which are essential for an agent to use it correctly. While the schema handles parameter documentation, the lack of annotations and output schema means the description should compensate more by explaining what the tool returns or how it behaves, which it fails to do adequately.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, meaning all parameters are documented in the input schema with descriptions and defaults. The description adds minimal value beyond this, as it doesn't explain parameter interactions (e.g., how 'savestate_path' or 'frames' affect the dump) or provide usage examples. With high schema coverage, the baseline score is 3, reflecting adequate but not enhanced parameter understanding from the description alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Dump entity/actor data from WRAM' with the goal of 'analyzing game objects'. It specifies the verb ('dump'), resource ('entity/actor data'), and source ('WRAM'), making it more specific than just the tool name. However, it doesn't explicitly differentiate from sibling tools like mgba_dump_oam or mgba_read_memory, which likely dump different types of data or from different memory regions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal usage guidance with 'useful for analyzing game objects', which implies a context but doesn't specify when to use this tool versus alternatives. There's no mention of when not to use it, prerequisites, or comparisons to sibling tools like mgba_dump_oam (which might dump sprite data) or mgba_read_memory (which might read arbitrary memory). This leaves the agent without clear direction on tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Dump OAM (Object Attribute Memory) sprite data - shows all 40 sprites with position, tile, flags, and palette
| Name | Required | Description | Default |
|---|---|---|---|
| rom_path | Yes | Path to the ROM file | |
| savestate_path | No | Optional savestate to load | |
| frames | No | Frames to run before dumping (default: 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but only states what data is shown, not behavioral traits like whether it modifies state, requires specific emulator setup, handles errors, or outputs format. It misses critical context for a tool that interacts with emulation state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose and key details without waste. Every word earns its place by specifying the action, resource, and data attributes clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of emulation tools and lack of annotations or output schema, the description is incomplete. It omits behavioral context, error handling, output format, and usage distinctions from siblings, leaving gaps for an AI agent to understand how to invoke it correctly in context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so parameters are well-documented in the schema. The description adds no additional parameter meaning beyond implying 'frames' relates to timing before dumping, which is already covered by the schema's default and description. Baseline 3 is appropriate as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Dump') and resource ('OAM sprite data'), with precise scope details ('all 40 sprites with position, tile, flags, and palette'). It distinguishes from siblings by focusing on OAM data rather than general entities, memory reads, or execution tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives like 'mgba_dump_entities' or 'mgba_read_memory' is provided. The description implies usage for sprite data analysis but lacks context on prerequisites, exclusions, or comparative scenarios with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read memory at specified addresses after running for some frames
| 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) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions running frames before reading, which adds some behavioral context, but fails to disclose critical traits: whether this is a read-only operation, what permissions or prerequisites are needed (e.g., ROM file access), how errors are handled, or what the output format looks like. For a tool with no annotations and 4 parameters, this is inadequate.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose ('Read memory at specified addresses') and adds necessary context ('after running for some frames'). There is zero waste, and every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description is incomplete for a tool with 4 parameters and behavioral complexity. It doesn't explain what the tool returns (e.g., memory values, error messages), nor does it cover prerequisites like ROM file format or savestate compatibility. For a read operation with frame execution, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents all 4 parameters. The description adds no parameter-specific semantics beyond implying that addresses are read after frame execution. Since the schema does the heavy lifting, the baseline score of 3 is appropriate, as the description doesn't compensate but doesn't detract either.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Read memory' and resource 'at specified addresses', specifying the action and target. It adds context about 'after running for some frames', which distinguishes it from a simple memory read. However, it doesn't explicitly differentiate from sibling tools like mgba_read_range, which likely reads a continuous range rather than discrete addresses.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions running frames before reading, but doesn't explain when this is necessary or preferable over other tools like mgba_read_range or mgba_dump_entities. There are no explicit when/when-not statements or named alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a contiguous range of memory addresses
| Name | Required | Description | Default |
|---|---|---|---|
| rom_path | Yes | Path to the ROM file | |
| start_address | Yes | Starting memory address | |
| length | Yes | Number of bytes to read | |
| savestate_path | No | Optional savestate to load | |
| frames | No | Frames to run before reading (default: 60) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure but only states the basic operation. It doesn't mention what happens when reading memory (does it require emulation to be running?), what format the output takes, whether there are limitations on address ranges, or what happens with invalid addresses. For a memory read operation with 5 parameters, this is insufficient behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently communicates the core function. There's no wasted language or unnecessary elaboration - every word serves the purpose of explaining what the tool does.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 5 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns (raw bytes? formatted data?), how errors are handled, or the relationship between parameters like 'savestate_path' and 'frames' with the memory reading operation. The context demands more complete information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, so all parameters are documented in the schema itself. The description adds no additional parameter information beyond what's already in the schema descriptions. This meets the baseline expectation when schema coverage is complete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Read') and resource ('contiguous range of memory addresses'), making the purpose immediately understandable. However, it doesn't distinguish this tool from sibling tools like 'mgba_read_memory' - both appear to read memory, so the specific distinction isn't explained.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance about when to use this tool versus alternatives. With sibling tools like 'mgba_read_memory' and 'mgba_dump_entities' available, there's no indication of what makes this tool the appropriate choice for reading a contiguous range versus other memory access methods.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a GB/GBC/GBA ROM for a specified number of frames and capture a screenshot
| Name | Required | Description | Default |
|---|---|---|---|
| rom_path | Yes | Path to the ROM file (.gb, .gbc, .gba) | |
| frames | No | Number of frames to run (default: 60) | |
| savestate_path | No | Optional path to a savestate file to load |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions running ROMs and capturing screenshots but lacks details on permissions, side effects (e.g., whether it modifies the ROM or savestate), rate limits, or error handling, leaving behavioral gaps for a tool with potential emulation complexities.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core functionality with zero wasted words, making it easy to understand at a glance without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description covers the basic action but lacks details on return values, error conditions, or deeper behavioral context. It's minimally adequate for a tool with 3 parameters but could be more informative about the screenshot output or execution nuances.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents parameters like rom_path, frames, and savestate_path. The description adds no additional meaning beyond what the schema provides, such as format details or usage context, meeting the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verbs ('Run', 'capture') and resources ('GB/GBC/GBA ROM', 'screenshot'), and distinguishes it from siblings like memory reading or Lua execution tools by focusing on emulation execution with visual output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for running ROMs and capturing screenshots, but provides no explicit guidance on when to use this tool versus alternatives like mgba_run_lua or other siblings, nor does it mention prerequisites or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run a custom Lua script in the emulator. The script can use emu:read8(), emu:write8(), emu:screenshot(), callbacks:add(), etc.
| Name | Required | Description | Default |
|---|---|---|---|
| rom_path | Yes | Path to the ROM file | |
| script | Yes | Lua script to execute. Use emu:quit() to exit. Write JSON to 'output.json' for structured data. | |
| savestate_path | No | Optional savestate to load | |
| timeout | No | Timeout in seconds (default: 30) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses key behavioral traits: the tool executes Lua scripts with emulator APIs, can output JSON, and has a timeout. However, it misses details like error handling, side effects on emulator state, or performance implications, which are important for a scripting tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose and efficiently lists example Lua functions and output instructions in a single, compact sentence. Every element adds value without redundancy, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of running custom scripts in an emulator, no annotations, and no output schema, the description is moderately complete. It covers basic functionality and output method but lacks details on return values, error cases, or integration with sibling tools, leaving gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents parameters like rom_path and script. The description adds minimal value beyond the schema, mentioning Lua functions and JSON output, but doesn't elaborate on parameter interactions or advanced usage, aligning with the baseline for high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Run a custom Lua script') and the target ('in the emulator'), which is specific and actionable. It distinguishes itself from sibling tools like mgba_run by specifying Lua scripting capabilities, though it doesn't explicitly contrast with all siblings like mgba_read_memory.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage through examples of Lua functions (emu:read8(), etc.), suggesting when to use this tool for custom scripting versus simpler read operations. However, it lacks explicit guidance on when to choose this over alternatives like mgba_run or mgba_read_memory, leaving some ambiguity.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
mgba_dump_entitiesmgba_dump_oammgba_read_memorymgba_read_rangemgba_runmgba_run_luaScored across 6 tools
Each tool has a clearly distinct purpose with no overlap: dumping entity data, dumping sprite data, reading specific memory addresses, reading memory ranges, running the emulator, and running Lua scripts. The descriptions make it easy to differentiate between them, eliminating any ambiguity.
All tools follow a consistent 'mgba_verb_noun' pattern (e.g., mgba_dump_entities, mgba_read_memory, mgba_run_lua). This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming style.
With 6 tools, the set is well-scoped for an emulator debugging server, covering core operations like memory access, emulation control, and scripting. Each tool earns its place without feeling excessive or insufficient for the domain.
The tools provide strong coverage for emulator interaction, including memory inspection, execution control, and custom scripting. A minor gap exists in write operations (e.g., no mgba_write_memory), but agents can work around this using mgba_run_lua for modifications.
Generate authentic pixel art - sprites, animations, and tilesets - from any MCP client
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Control real Android and iOS devices with LLM agents — tap, swipe, type, automate flows.
Manage Sprites: sandboxed compute environments with exec, services, and checkpoints.
