<div align="center">

BizHawk Emulator MCP

Deterministic BizHawk control over MCP for Game Boy, Mega Drive/Genesis, NES, and SNES.

</div>

What is this?

This project exposes BizHawk as an MCP server. It sends input, frame-step, screenshot, reset, savestate, and memory-read commands through a portable Lua bridge that exchanges atomic files with Python. JSON scenarios make emulator checks repeatable without requiring a BizHawk plugin or a socket service.

The package does not include BizHawk or ROMs. Use legally obtained ROMs and install BizHawk separately.

Quick start

The supported deployment is a normal Python installation plus one project home shared by the MCP client and BizHawk.

git clone https://github.com/KanonZombie/emulator-mcp.git
Set-Location emulator-mcp

python -m venv .venv
& .\.venv\Scripts\python.exe -m pip install .
& .\.venv\Scripts\emulator-mcp.exe init .emulator-mcp
& .\.venv\Scripts\emulator-mcp.exe --version

init creates the portable bridge and empty runtime directories:

.emulator-mcp/
  bizhawk/bridge.lua
  runtime/gb/
  runtime/md/
  runtime/nes/
  runtime/snes/

The command is safe to run again after upgrading the package; it refreshes the bridge and keeps existing runtime files.

Start BizHawk

1. Open a legally obtained ROM in BizHawk.
2. Open Tools > Lua Console.
3. Load .emulator-mcp/bizhawk/bridge.lua.
4. Leave the Lua script running. BizHawk stays paused between commands.

The bridge detects the loaded core and selects its runtime automatically:

BizHawk core	MCP target	Buttons
Game Boy / Game Boy Color	gb	A, B, Start, Select, D-pad
Genesis / Mega Drive	md	A, B, C, X, Y, Z, Mode, Start, D-pad
NES	nes	A, B, Start, Select, D-pad
SNES	snes	A, B, X, Y, L, R, Start, Select, D-pad

Run one BizHawk instance per active target. Each instance must load the bridge from the same .emulator-mcp directory configured for the MCP client.

Run directly from a checkout

For local development, you can use the repository as the project home without running init. In PowerShell, set the environment variable before launching BizHawk. Replace these example paths with the locations on your machine:

$env:EMULATOR_MCP_HOME = "C:\path\to\emulator-mcp"

& "C:\path\to\BizHawk\EmuHawk.exe" `
  "--lua=C:\path\to\emulator-mcp\bizhawk\bridge.lua" `
  "C:\path\to\roms\game.gb"

This starts BizHawk with the Game Boy ROM and the repository bridge. Runtime files are written under runtime/gb/, which is ignored by Git. The variable only applies to the current PowerShell session; configure the same EMULATOR_MCP_HOME in the MCP client if it is launched separately.

Configure an MCP client

Use absolute paths. Replace both placeholders in this example with the paths on the machine that runs the client:

{
  "mcpServers": {
    "bizhawk": {
      "command": "C:\\path\\to\\emulator-mcp\\.venv\\Scripts\\emulator-mcp.exe",
      "env": {
        "EMULATOR_MCP_HOME": "C:\\path\\to\\emulator-mcp\\.emulator-mcp"
      }
    }
  }
}

EMULATOR_MCP_HOME is the authoritative project home. The Python server and the Lua bridge must point to the same directory. If the command is installed with pipx, use emulator-mcp as the command and keep the same environment variable.

Verify the connection

These commands use the same implementation as the MCP tools and require the bridge to be running in BizHawk:

& .\.venv\Scripts\emulator-mcp.exe --target gb --test bridge-info
& .\.venv\Scripts\emulator-mcp.exe --target gb --test status
& .\.venv\Scripts\emulator-mcp.exe --target nes --test buttons
& .\.venv\Scripts\emulator-mcp.exe --target snes --test tap START 8 2
& .\.venv\Scripts\emulator-mcp.exe --target snes --test screenshot title

bridge-info should report bridge version 1.1.0. A timeout normally means that the Lua script is not running or EMULATOR_MCP_HOME points to a different directory.

CLI command reference

With no arguments, the installed executable starts the stdio MCP server. With --test, it runs one diagnostic command and prints its result.

Process commands

Command	Arguments	Description
emulator-mcp	none	Start the MCP server over stdio.
emulator-mcp --help	none	Show short help; -h is also accepted.
emulator-mcp --version	none	Print the package version.
emulator-mcp init	[directory]	Copy bridge.lua and create runtime directories. Defaults to .emulator-mcp.
emulator-mcp --target TARGET --test COMMAND	see below	Run a diagnostic against gb, md, nes, or snes; target defaults to gb.

init is idempotent: it refreshes the copied bridge without removing runtime files. Use this prefix for the diagnostic commands:

& .\.venv\Scripts\emulator-mcp.exe --target gb --test COMMAND [ARGUMENTS]

Emulator test commands

Command	Arguments and defaults	Description
status	none	Return system, frame, and screen size.
bridge-info	none	Return bridge version, detected system, and capabilities.
buttons	none	Return BizHawk button names and current states.
read-memory	<address> [length=1] [domain=System Bus]	Read a memory range and return its bytes as uppercase hexadecimal. Addresses accept decimal or 0x hexadecimal notation; length is limited to 64 KiB.
step	[frames=1]	Advance neutral input; frames are clamped to 1--600.
tap	<button> [hold_frames=8] [release_frames=2]	Tap a button; hold is clamped to 1--120 and release to 1--600.
hold	<button> [frames=1]	Hold a button; frames are clamped to 1--120.
release	[frames=2]	Release all buttons; frames are clamped to 1--600.
reset	[settle_frames=60]	Reboot and settle with neutral input; frames are clamped to 1--600.
press	<button> [frames=1]	Legacy alias for tap with two release frames.
save-state	[name=state]	Save a state under the selected target runtime.
load-state	[name=state]	Load a state from the selected target runtime.
create-baseline	[name=baseline]	Alias for save-state.
load-baseline	[name=baseline]	Alias for load-state.
screenshot	[name=shot]	Save a screenshot under the selected target runtime.
gb-gpu-snapshot	[name=snapshot] [--no-render]	Capture Game Boy DMG GPU data; target must be gb.
run-scenario	<path>	Run a JSON scenario against the selected target.
run-pair-scenario	<path>	Run the GB and Mega Drive entries in a pair scenario.
build-contact-sheet	<pair_summary_path>	Rebuild a pair contact sheet from an existing summary.
build-pair-diffs	<pair_summary_path>	Rebuild crops, diffs, and the pair contact sheet.

gb-gpu-snapshot --no-render skips diagnostic PNG panels. Pair commands use the pair file's GB/MD entries; the target option is not needed.

& .\.venv\Scripts\emulator-mcp.exe --target md --test status
& .\.venv\Scripts\emulator-mcp.exe --target gb --test tap A 8 2
& .\.venv\Scripts\emulator-mcp.exe --target md --test read-memory 0xFFE75E 2 "M68K BUS"
& .\.venv\Scripts\emulator-mcp.exe --target gb --test read-memory 0xC000 16 "System Bus"
& .\.venv\Scripts\emulator-mcp.exe --target gb --test save-state title_screen
& .\.venv\Scripts\emulator-mcp.exe --test run-pair-scenario scenarios/pairs/title_start.json

Memory read examples

read-memory uses the exact BizHawk memory-domain name. These examples read the main RAM and video memory for each supported console:

Mega Drive / Genesis

# Main 68K RAM: bus address FF0000--FFFFFF
& .\.venv\Scripts\emulator-mcp.exe --target md --test read-memory 0xFFE75E 16 "M68K BUS"

# VDP video RAM: domain-relative address 0000--FFFF
& .\.venv\Scripts\emulator-mcp.exe --target md --test read-memory 0x0000 16 "VRAM"

Game Boy / Game Boy Color

# Work RAM (WRAM): CPU address C000--DFFF
& .\.venv\Scripts\emulator-mcp.exe --target gb --test read-memory 0xC000 16 "System Bus"

# Video RAM (VRAM): CPU address 8000--9FFF
& .\.venv\Scripts\emulator-mcp.exe --target gb --test read-memory 0x8000 16 "System Bus"

For Mega Drive, 0xE75E in a RAM Watch RAM domain corresponds to 0xFFE75E in M68K BUS. Sign-extended values such as 0xFFFFE75E are normalized to the same bus address. Memory reads return uppercase hexadecimal bytes and do not advance the emulator frame.

MCP tools

Generic tools accept target="gb", "md", "nes", or "snes":

Tool	Parameters	Description
emulator_status	target="gb"	Return system, frame, and screen size.
emulator_bridge_info	target="gb"	Return bridge version and capabilities.
emulator_buttons	target="gb"	Return BizHawk button names and states.
emulator_read_memory	target="gb", address, length=1, domain="System Bus"	Read a memory range and return uppercase hexadecimal bytes. Maximum length is 64 KiB.
emulator_step	target="gb", frames=1	Advance neutral input; frames 1--600.
emulator_tap	target="gb", button="", hold_frames=8, release_frames=2	Tap one button; hold 1--120 and release 1--600.
emulator_hold	target="gb", button="", frames=1	Hold one button; frames 1--120.
emulator_release	target="gb", frames=2	Release all buttons; frames 1--600.
emulator_reset	target="gb", settle_frames=60	Reboot and settle; frames 1--600.
emulator_screenshot	target="gb", name="shot"	Save a screenshot and return its path.
emulator_save_state	target="gb", name="state"	Save a named state.
emulator_load_state	target="gb", name="state"	Load a named state.
emulator_create_baseline	target="gb", name="baseline"	Alias for saving a named state.
emulator_load_baseline	target="gb", name="baseline"	Alias for loading a named state.
emulator_run_scenario	path, target="gb"	Run a JSON scenario against a target.

Additional tools cover Game Boy GPU snapshots and GB/Mega Drive pair scenarios:

Tool	Parameters	Description
emulator_gb_gpu_snapshot	target="gb", render=True, include_raw=True, output_dir=None, name="snapshot"	Capture DMG GPU data and optionally render PNG panels. Only target gb.
gb_gpu_snapshot	render=True, include_raw=True, output_dir=None	Legacy short alias for the Game Boy snapshot tool.
emulator_run_pair_scenario	path	Run the GB and Mega Drive scenarios in a pair definition.
emulator_build_pair_contact_sheet	pair_summary_path	Rebuild a pair contact sheet.
emulator_build_pair_diffs	pair_summary_path	Rebuild crops, visual diffs, and the contact sheet.

The original Game Boy-only MCP names remain available as legacy aliases:

Tool	Parameters	Description
bizhawk_status	none	Alias for emulator_status(target="gb").
bizhawk_bridge_info	none	Alias for emulator_bridge_info(target="gb").
bizhawk_step	frames=1	Alias for emulator_step(target="gb").
bizhawk_tap	button, hold_frames=8, release_frames=2	Alias for emulator_tap(target="gb").
bizhawk_hold	button, frames	Hold a Game Boy button; frames 1--120.
bizhawk_release	frames=2	Alias for emulator_release(target="gb").
bizhawk_reset	settle_frames=60	Alias for emulator_reset(target="gb").
bizhawk_press	button, frames=1	Legacy tap alias with two release frames.
bizhawk_screenshot	name="shot"	Alias for emulator_screenshot(target="gb").
bizhawk_save_state	name	Save a named Game Boy state.
bizhawk_load_state	name	Load a named Game Boy state.
bizhawk_create_baseline	name	Save a named Game Boy baseline.
bizhawk_load_baseline	name	Load a named Game Boy baseline.
bizhawk_read_memory	address, length=1, domain="System Bus"	Legacy Game Boy memory-read alias.
bizhawk_run_sequence	operations	Run a list of scenario operations against Game Boy.
bizhawk_run_scenario	path	Run a JSON scenario against Game Boy.

Scenario operations

The steps array accepts one operation object per sequence:

Operation	Fields	Description
tap	tap, hold_frames=8, release_frames=2	Tap a button.
press	press, frames=8, release_frames=2	Legacy tap spelling.
hold	hold, frames=1	Hold a button.
release	release	Release all buttons for that many frames.
step	step	Advance neutral frames.
screenshot	screenshot	Capture a named screenshot in the run directory.
gb_gpu_snapshot	gb_gpu_snapshot	Capture a named Game Boy GPU snapshot.
gpu_snapshot	string or {name, render, include_raw}	Capture a GPU snapshot with options.

Scenarios can use start.mode values none, reset, or load_state, plus the legacy top-level load_state and optional save_state_after fields.

Input semantics

• tap holds one button and adds neutral frames before/after it.
• hold holds one button without an automatic final release.
• release releases every known button for the requested number of frames.
• step advances with neutral input.
• reset reboots the core and advances neutral settling frames.

Frame counts are bounded by both the server and the bridge. Button names are case-insensitive. Memory reads return an uppercase hex field and do not advance the emulator frame. For Mega Drive, use the exact M68K BUS domain; the sign-extended address 0xFFFFE75E is normalized to bus address 0xFFE75E, corresponding to offset 0xE75E in the main RAM domain.

Scenarios

Scenarios are plain JSON. Paths are resolved relative to the scenario file for pair scenarios and relative to the current directory for direct CLI use.

{
  "id": "nes.title_start",
  "description": "Boot and press Start",
  "start": { "mode": "reset", "settle_frames": 60 },
  "steps": [
    { "step": 300 },
    { "screenshot": "title" },
    { "tap": "START", "hold_frames": 8, "release_frames": 2 },
    { "step": 60 },
    { "screenshot": "after_start" }
  ],
  "save_state_after": "after_start"
}

Run a scenario with:

& .\.venv\Scripts\emulator-mcp.exe --target nes --test run-scenario scenarios/nes/title_start.json

Supported starts are none, reset, and load_state. Run artifacts are written below .emulator-mcp/runtime/<target>/runs/ and are intentionally ignored by Git.

Configuration

Variable	Purpose
EMULATOR_MCP_HOME	Absolute project home shared by Python and BizHawk.
BIZHAWK_GB_BRIDGE_DIR	Optional Game Boy runtime directory override.
BIZHAWK_MD_BRIDGE_DIR	Optional Mega Drive runtime directory override.
BIZHAWK_NES_BRIDGE_DIR	Optional NES runtime directory override.
BIZHAWK_SNES_BRIDGE_DIR	Optional SNES runtime directory override.
BIZHAWK_BRIDGE_DIR	Legacy Game Boy runtime override.

Prefer EMULATOR_MCP_HOME; the target-specific variables exist for compatibility and isolated runtime layouts. Empty overrides are ignored.

Project structure

.github/
  workflows/
bizhawk/
docs/
  ai/
scenarios/
  gb/
  md/
  nes/
  pairs/
  snes/
server/
  tests/
AGENTS.md
LICENSE
README.md
pyproject.toml
requirements.txt

Generated directories are deliberately absent from the tree: .venv/, build/, dist/, runtime/, and .emulator-mcp/ stay local.

Development and release checks

python -m venv .venv
& .\.venv\Scripts\python.exe -m pip install .
& .\.venv\Scripts\python.exe -m unittest discover -s server/tests -v
& .\.venv\Scripts\python.exe -m pip wheel . --no-deps -w dist

The unit tests do not require an emulator. For a BizHawk release smoke test, provide the executable and local ROMs explicitly:

& .\.venv\Scripts\python.exe server/tests/bizhawk_smoke.py `
  --bizhawk "C:\\path\\to\\BizHawk\\EmuHawk.exe" `
  --rom gb="C:\\path\\to\\roms\\game.gb" gb

Never commit ROMs, savestates, screenshots, logs, command/response files, virtual environments, or generated build output. Check the result before sharing changes:

git status --short --ignored

Troubleshooting

• Timeout: reload and run .emulator-mcp/bizhawk/bridge.lua, then verify that the MCP client's EMULATOR_MCP_HOME is the same absolute directory.
• Old or unknown command: reinstall the package in the MCP client's Python environment, run emulator-mcp init .emulator-mcp again, and reload the Lua script in BizHawk. A running MCP client may also need to be restarted.
• Unsupported system: open a GB/GBC, Genesis, NES, or SNES ROM before loading the bridge.
• Wrong buttons: call emulator_buttons; BizHawk exposes the core's exact names.
• Missing state: states are target-specific and live under that target's runtime directory.

Documentation

Resource	Description
AGENTS.md	Repository layout, commands, style, and contribution rules.
pyproject.toml	Package metadata, dependencies, and CLI entry point.
bizhawk/bridge.lua	Portable BizHawk file bridge.
server/mcp_server.py	MCP tools, CLI, scenarios, and runtime protocol.
server/tests	Unit tests and optional BizHawk smoke runner.
scenarios	Target-specific and paired JSON flows.

Contributing

Keep changes focused, add one regression test for non-trivial behavior, run the unit tests and wheel build, and keep emulator artifacts outside version control. Pull requests should include the exact commands run and any relevant BizHawk smoke-test output.

<a href="https://github.com/KanonZombie/emulator-mcp/graphs/contributors"> <img src="https://contrib.rocks/image?repo=KanonZombie/emulator-mcp" /> </a>

License

MIT. See LICENSE.

---

<div align="center">

</div>