dmang-dev/mcp-bizhawk

An MCP server that exposes BizHawk — the multi-system emulator the TAS community lives in — to any MCP-compatible client (Claude Desktop, Claude Code, etc.).
One bridge, **many systems**: NES, SNES, Game Boy / GBC / GBA, Sega Master System / Genesis / 32X / Saturn, N64, PlayStation 1, Atari 2600/5200/7800, Lynx, ColecoVision, Intellivision, and more — all through the same MCP tools, with per-system memory domains exposed cleanly.
Claude (the agent) drives Samus through the opening of Ceres Station — all input batched through bizhawk_play_input_sequence , all motion verified by reading WRAM addresses found via live RAM-hunt. Recording is 2× speed; the actual playback runs at native 60fps emulation. See docs/RECIPES.md and docs/SUPER-METROID-ADDRESSES.md for the workflow.
How it works
(Adjust port if you're overriding BIZHAWK_PORT.)
Alternative: configure persistently via **Settings → Customize → External Tools** in BizHawk's UI.
2. Load the bridge script
In BizHawk: **Tools → Lua Console → Open Script** → select lua/bridge.lua from this repo.
You should see in the Lua Console:
And in the mcp-bizhawk process's stderr:
Register with your MCP client
Claude Code (CLI)
Verify:
Claude Desktop
Edit claude_desktop_config.json:
| Platform | Path |
|---|---|
| macOS | ~/Library/Application Support/Claude/claude_desktop_config.json |
| Windows | %APPDATA%\Claude\claude_desktop_config.json |
| Linux | ~/.config/Claude/claude_desktop_config.json |
Restart Claude Desktop after editing.
Other MCP clients
The server speaks standard MCP over stdio. Run mcp-bizhawk and connect any MCP client to its stdio.
Configuration
| Env var | Default | Purpose |
|----------------|---------------|--------------------------------------|
| BIZHAWK_HOST | 127.0.0.1 | TCP host to listen on for BizHawk |
| BIZHAWK_PORT | 8766 | TCP port to listen on for BizHawk |
Tools
| Tool | Description |
|------|-------------|
| bizhawk_ping | Verify bridge connectivity (returns pong) |
| bizhawk_get_info | ROM name, ROM hash, framecount, memory domains, capabilities |
| bizhawk_list_memory_domains | List available memory domains for the loaded core |
| bizhawk_read8 / bizhawk_read16 / bizhawk_read32 | Read u8 / u16-LE / u32-LE from memory |
| bizhawk_write8 / bizhawk_write16 / bizhawk_write32 | Write to memory |
| bizhawk_read_range | Read up to 4096 bytes as a byte array |
| bizhawk_write_range | Write up to 4096 bytes from a byte array |
| bizhawk_press_buttons | Set joypad state for one player; keys are button names, values booleans |
| bizhawk_frame_advance | Step the emulator by N frames |
| bizhawk_pause / bizhawk_unpause | Pause / resume emulation |
| bizhawk_reset | Reset the loaded core |
| bizhawk_screenshot | Save a PNG of the current display to a path |
| bizhawk_save_state / bizhawk_load_state | Save / load emulator state to a file path |
All memory r/w tools take an optional domain parameter — if omitted, the active "current" memory domain is used. Use bizhawk_list_memory_domains to discover the names available on the loaded core.
See docs/RECIPES.md for end-to-end examples (RAM hunting on SNES/NES/N64, frame-precise input, snapshot-experiment-restore, cross-system regression testing) and CHANGELOG.md for release history.
Memory domains by system (cheat sheet)