bus-pirate-mcp

An agentic HTTP/MCP bridge and a web console for the Dangerous Prototypes Bus Pirate — the little USB serial multi-tool that speaks I2C, SPI, UART, 1-Wire and friends.

It wraps the Bus Pirate's terminal protocol behind a small REST API so an agent (or you, from a browser) can list serial ports, identify the board, switch bus modes, and scan an I2C bus for devices. Writes to a live bus can damage hardware, so anything beyond read/scan is gated behind BUSPIRATE_ALLOW_RAW.

Web console

Start the server and open http://127.0.0.1:3082 for a built-in console: pick a port, connect, read board info/voltages, switch bus mode, scan I2C, identify/dump SPI flash, and (optionally) send raw terminal commands — all with live output.

Android (USB OTG)

No PC required: the android/ folder is a native Kotlin/Compose app that drives the Bus Pirate straight from a phone or tablet over a USB-OTG cable (no root), using usb-serial-for-android. Same workflow — connect, scan I2C, identify and dump SPI flash for firmware hacking.

API

• GET /health — service status, whether serialport is available, current connection/mode
• GET /actions — list of supported actions
• GET /ports — enumerate serial ports
• POST /connect — { "device": "COM5", "baud": 115200 }
• POST /disconnect
• POST /info — runs the i command
• POST /voltages — runs the v command
• POST /mode — { "mode": "i2c" } (hiz|1wire|uart|i2c|spi|2wire|3wire|lcd)
• POST /scan/i2c — runs the I2C (1) search macro, returns parsed 7-bit addresses
• POST /spi/id — runs SPI RDID (0x9F), decodes the 3-byte JEDEC id into manufacturer + capacity
• POST /spi/dump — { "addr": 0, "length": 256 } runs SPI READ (0x03), returns bytes + a hex dump
• POST /raw — { "command": "[0x70 0x00 r]" } (requires BUSPIRATE_ALLOW_RAW=1)

All responses are JSON: { "ok": true, "requestId": "…", "action": "…", … } or { "ok": false, "action": "…", "error": "…" }.

Local run

npm install
npm start
# open http://127.0.0.1:3082

Or run directly from npm without cloning:

npx bus-pirate-mcp
# open http://127.0.0.1:3082

serialport is an optional dependency: the server and tests run without it, but hardware actions return a clear error until it's installed.

Docker run

docker build -t eoinedge/bus-pirate-mcp:latest .
docker run --rm --network host \
  -e PORT=3082 \
  --device /dev/ttyUSB0 \
  eoinedge/bus-pirate-mcp:latest

Health check:

curl -s http://127.0.0.1:3082/health

Environment

• PORT default 3082
• BUSPIRATE_DEVICE default empty (must pass device on connect, e.g. /dev/ttyUSB0 or COM5)
• BUSPIRATE_BAUD default 115200
• BUSPIRATE_IDLE_MS default 400 — idle gap that ends a read
• BUSPIRATE_TXN_TIMEOUT_MS default 8000 — hard cap per command
• BUSPIRATE_ALLOW_RAW default 0 — set 1 to enable POST /raw

Safety

The Bus Pirate drives real voltage onto real pins. Read/scan operations are safe; raw writes are not. Keep BUSPIRATE_ALLOW_RAW=0 unless you know exactly what you're poking, and never point this at a bus you can't afford to brick.

License

MIT © Eoin Jordan