# dmang-dev/mcp-bizhawk [Health: Active]

**Category:** 🎮 Gaming  
**Repository:** https://github.com/dmang-dev/mcp-bizhawk  
**GitHub Stars:** 4  
**npm Downloads (last month):** 94  
**Views:** 6  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/dmang-dev-mcp-bizhawk

## Description
Drive the BizHawk multi-system emulator from any MCP client. Memory r/w across named domains, joypad input, frame-advance, screenshot, save/load state. One bridge unlocks NES, SNES, GB/GBC/GBA, Genesis, N64, PSX, Saturn, and more.

## Tools
Capabilities this server exposes over MCP:

- **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** — Read u8 / u16-LE / u32-LE from memory
- **bizhawk_write8** — 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** — Pause / resume emulation
- **bizhawk_reset** — Reset the loaded core
- **bizhawk_screenshot** — Save a PNG of the current display to a path
- **bizhawk_save_state** — Save / load emulator state to a file path

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-bizhawk": {
    "command": "npx",
    "args": ["-y","mcp-bizhawk"],
    "env": {
      "BIZHAWK_HOST": "",
      "BIZHAWK_PORT": ""
    }
  }
}
```

**Requires environment variables:** `BIZHAWK_HOST`, `BIZHAWK_PORT` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What dmang-dev/mcp-bizhawk MCP server does

The dmang-dev/mcp-bizhawk MCP server lets an MCP-compatible client operate a running BizHawk instance. It supports systems handled by BizHawk, including NES, SNES, Game Boy, Game Boy Color, Game Boy Advance, Genesis, Saturn, N64, PlayStation 1, Atari systems, Lynx, ColecoVision, and Intellivision. The exact available memory domains depend on the loaded core and ROM.

An agent can inspect the loaded game and emulator state, discover memory domains, read or modify memory, send joypad input, advance or pause emulation, reset the core, capture the display as a PNG, and save or restore emulator state. Memory operations can target a named domain or use the active current domain. Range operations support up to 4096 bytes.

## How it works

The setup has two cooperating components. A Node.js MCP process provides standard MCP over stdio and listens for BizHawk connections on a local TCP port. The `lua/bridge.lua` script runs inside BizHawk’s Lua Console and polls that listener once per frame, forwarding commands and responses using newline-delimited JSON.

This architecture is useful when the client needs frame-by-frame inspection or controlled experimentation. The connection model adds approximately one frame of delay per request, estimated at about 16 milliseconds at 60 Hz. It is therefore less suitable for scripts that require a high rate of calls.

## Setup and configuration

The dmang-dev/mcp-bizhawk MCP server requires BizHawk 2.6.2 or newer and Node.js 22 or newer. Install the package from npm with `npm install -g mcp-bizhawk`, or run it without a global installation using `npx -y mcp-bizhawk`.

Start the MCP process, then configure BizHawk to connect to the listener at `127.0.0.1:8766` by using its socket options or the External Tools settings. Open BizHawk’s Lua Console and load `lua/bridge.lua` from the repository. The MCP client must then be configured to launch the `mcp-bizhawk` command over stdio. The README gives registration steps for Claude Code and Claude Desktop, and states that other standard MCP clients can use the same stdio transport.

The listener address is configurable with `BIZHAWK_HOST`, which defaults to `127.0.0.1`, and `BIZHAWK_PORT`, which defaults to `8766`.

## Tools and capabilities

The dmang-dev/mcp-bizhawk MCP server exposes tools for:

- Checking connectivity and retrieving ROM name, ROM hash, frame count, domains, and capabilities.
- Listing memory domains and reading or writing 8-, 16-, and 32-bit values.
- Reading or writing byte ranges up to 4096 bytes.
- Setting one player’s button state with core-specific button names.
- Advancing a chosen number of frames, pausing or resuming, and resetting the loaded core.
- Saving screenshots to PNG paths.
- Saving and loading emulator states from file paths.

## Limitations and notes

The Lua bridge must be loaded inside BizHawk; installing the npm package alone does not attach it to an emulator. Memory-domain names and controller button names vary by system, so clients should query the loaded core before issuing system-specific operations. BizHawk’s version must meet the stated minimum because earlier releases use a different socket-server wire format.

_Full upstream README: https://allmcps.com/mcp/dmang-dev-mcp-bizhawk/readme_