bitpirate-mcp

An MCP server for the ESP32-Bit-Pirate - an open-source, ESP32-S3-based clone of the Bus Pirate multibus tool. It exposes the bench's UART, SPI (incl. the on-device flash shell), I2C, 1-Wire and GPIO capabilities as MCP tools over stdio, so an AI agent can probe, dump and analyze firmware on a target board end-to-end: attach a device to the ESP32, let the agent drive the tools, and get extracted binaries and analysis out the other end.

A port of buspirate-mcp (Marc Plogas, MIT) from the BusPirate 6's BPIO2 binary protocol to the Bit-Pirate's text-console protocol. The tool/dispatch/session/safety layers are largely kept verbatim; the device layer was replaced and re-grounded in the Bit-Pirate v1.8 firmware source.

What makes this different from the upstream

Gains: the Bit-Pirate is stronger for RE than the BP6 in one key respect - the firmware does binary analysis on the device (39 secret patterns, file signature table, entropy), so spi_flash_analyze returns findings without pulling the whole image first. It is also cheaper (~$15 board + devkit vs $100+).

Related MCP server: agentic-hil

Architecture

MCP client (Claude Code, Hermes, any MCP host)
  |  stdio
  v
server.py            tool definitions + dispatch + safety tiers + session mgmt
  |
  v
tools.py             33 tool implementations (protocol-agnostic where possible)
  |
  v
bitpirate_hardware.py  THE device layer (the only firmware-specific module)
  |  pyserial, /dev/ttyACM0 @115200
  v
ESP32-S3 running ESP32-Bit-Pirate v1.8 text console

The console driver has two read modes, both grounded in the firmware's actual output:

• Prompt-aware reads - command, then read until the trailing mode prompt (DIO> , SPI> , …) matches at the end of the transcript. Used for mode switches, DIO, and instruction-syntax transactions.

• Marker-aware reads - shell flows (flash shell, config wizard) don't end at a mode prompt; the driver reads until a known completion marker (=== SPI Flash Shell ===, SPI Flash Dump: Done., SPI configured., …) and answers intermediate prompts in the exact order the firmware asks them.

A quadratic-echo line-length guard (250 chars) protects the firmware's getLine input path.

Every command string in the driver was taken from the v1.8 firmware source - SpiFlashShell.cpp, SpiController.cpp, DioController.cpp, UserInputManager.cpp, ActionDispatcher.cpp - not assumed.

Tools (33)

Approval-tier tools require an explicit _confirmed: true and the firmware's own confirmation prompts are driven - double-gated for destructive operations.

Install

# any Python 3.10+ (tested on 3.11)
git clone https://github.com/Indigaz/bitpirate-mcp
cd bitpirate-mcp
python3 -m venv .venv          # or: uv venv --python 3.11 .venv
.venv/bin/pip install -e .

Register with an MCP host (.mcp.json):

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

Board requirements: an ESP32-S3 devkit running ESP32-Bit-Pirate v1.x, exposing a USB CDC console (/dev/ttyACM0 on Linux). No pin configuration needed for first use - the firmware keeps its SPI pin map in NVS (defaults on a typical Bit-Pirate build: MOSI 40, MISO 39, SCLK 41, CS 4, 20 MHz, WP 7); spi_config re-points any free GPIO.

Typical RE workflow

1. Attach a target to the bench (SPI flash via clip, or I2C bus).

2. spi_probe - identify the chip (ID, manufacturer, capacity).

3. spi_dump → ~/re-lab/<target>/flash.bin - raw image off the bus.

4. spi_flash_analyze / spi_flash_strings / spi_flash_search - on-device findings (what firmware, embedded keys, embedded binaries).

5. Hand the image to your static-analysis tooling (Ghidra, REA, etc.).

Testing & verification

• 221 tests, all passing. The device layer is tested with a transcript-driven protocol mock (FakeSerial): scripted firmware transcripts are released only after the triggering command is written, simulating real round-trip latency so command/response pairing cannot bleed across commands. The mock is a FIFO of (line → response) so repeated prompts (e.g. y/y) resolve in firmware order, and it accepts raw bytes for the dump path.

• Live-verified on hardware (ESP32-S3 devkit + Bit-Pirate v1.8, no target attached - no-chip paths):

  • DIO: read, edge counter, and electrical drive-HIGH/LOW self-test

  • instruction syntax: [0x9F r:3] → 00 00 00 (floating bus, correct)

  • flash shell: probe (no-chip detection), analyze short-circuit, clean shell exit

• Reproduce the live smoke tests: scripts/smoke_live.py, scripts/smoke_live_spi.py (read-only by design).

Roadmap

• Phase 3 - I2C/1-Wire sessions rewritten against the firmware's native controllers (scan/read/write/dump + I2C monitor/glitch when grounded); SPI EEPROM shell (24cxx/25xxx - matches common bench EEPROMs).

• Phase 4 - read_flash via the firmware UART bridge + esptool (transparent bridge is persistent; requires a button/USB-replug to exit).

• Phase 5 - packaging: rename the buspirate_mcp package to bitpirate_mcp, PyPI publish, CI.

Credits

• Upstream: buspirate-mcp by Marc Plogas (MIT) - the tool/dispatch/session/ safety architecture it builds on.

• Hardware & firmware: ESP32-Bit-Pirate by geo-tp (the console protocol, flash shell and analyzer this port drives).

• Port to the ESP32-Bit-Pirate: designed and implemented by Hermes Agent (Nous Research)

  • the LLM agent driving this bench - under direction by Christian Brooks (Indigaz), who owns the hardware, set the goals, and reviews the work.

• Method: every firmware-facing string is grounded in v1.8 source; the whole port is test-first (221 tests) and smoke-tested against the real board before each phase ships.

License

MIT - see LICENSE. Upstream copyright (c) Marc Plogas; port copyright (c) 2026 Hermes Agent (Nous Research) / Christian Brooks.