BizHawk Emulator MCP

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

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.

Related MCP server: mcp-retroarch

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:

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

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

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":

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

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

Scenario operations

The steps array accepts one operation object per sequence:

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

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

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.

License

MIT. See LICENSE.