buspirate-mcp

MCP server for BusPirate 6 hardware security testing. Exposes UART, SPI, I2C, 1-Wire, power supply, GPIO, and logic analyzer operations as Model Context Protocol tools over stdio transport. 33 tools across 4 bus protocols + logic analyzer.

Built for use with Claude Code but works with any MCP client.

What it does

• UART probing: detect baud rates, capture serial output, interact with debug consoles

• SPI flash: probe JEDEC ID, read/dump/write SPI flash chips (W25Q series, SOIC-8 clip)

• I2C bus: scan for devices, read/write registers, dump EEPROM contents

• 1-Wire: enumerate devices, read ROM codes (DS18B20, iButton)

• Power control: voltage/current management with safety tiers

• GPIO control: toggle pins for bootloader entry (ESP32, ESP8266, etc.)

• Flash extraction: dump firmware through UART bridge via esptool

• Logic analyzer: follow-along capture at 75 MHz on all 8 IO pins with protocol identification

• Engagement logging: per-protocol logs (UART text, SPI/I2C/1-Wire JSONL), per-engagement folders

Requirements

• Python 3.11+

• BusPirate 6 with BPIO2 binary mode enabled

• User in dialout group for serial access (sudo usermod -aG dialout $USER)

Install

git clone --recurse-submodules https://github.com/mplogas/buspirate-mcp.git
cd buspirate-mcp
pip install -e ".[dev]"

MCP Client Configuration

Copy the example config and adjust paths for your machine:

cp .mcp.json.example .mcp.json
# Edit .mcp.json with the absolute path to your venv's python

The .mcp.json is gitignored since paths are machine-specific. Example config:

{
  "mcpServers": {
    "buspirate": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "buspirate_mcp"]
    }
  }
}

Set PIDEV_ENGAGEMENTS_DIR environment variable to control where engagement logs are written. Defaults to ./engagements/ relative to the package root.

Tools

Safety Model

Three tiers enforced at the MCP server boundary:

• read-only: full autonomy, no side effects

• allowed-write: autonomous execution, all calls logged

• approval-write: blocks until human confirms via _confirmed parameter. Wrong voltage fries chips. SPI flash writes and I2C writes overwrite data irreversibly.

BusPirate 6 Setup

Enable BPIO2 binary mode

Connect to the BP6 terminal port (ACM0) and run:

binmode -> select 2 (BPIO2 flatbuffer interface) -> y to save

This persists across reboots.

Pin mapping

UART mode uses IO4 (TX->) and IO5 (RX<-). The BP6 display is the authoritative source for pin assignment.

Free pins (IO0-IO3, IO6-IO7) can be used for GPIO control (bootloader entry, reset) while UART is active.

Project integration

The open_uart tool accepts an optional project_path parameter. When provided (from project-mcp's create_project), engagement data is written to <project_path>/uart/ instead of creating a standalone folder. Omit it for standalone use.

Known limitations

• Bridge mode exit: after flash dump operations, bridge mode stays active. Press the physical BP6 button or USB-replug to exit.

• Dual-port operation: BPIO2 (binary port) and bridge mode (terminal port) cannot operate simultaneously.

• Baud scan timing: fast-booting targets may finish output before the scan reaches the correct rate.

• Port numbering: the binary port number may change after USB replug (ACM1 -> ACM2). The server auto-detects.

Tests

pytest              # 203 tests, no hardware needed
pytest -m hardware  # integration tests, BP6 must be connected

License

MIT