Bench

[Bench]

Bench

Made by Seaynic Labs. Need tools like this built around your own systems? We do that.

USB hardware discovery for your AI tools.

Bench is a native macOS MCP server for developers who work with boards plugged into their Mac: Arduino, ESP32, Raspberry Pi Pico and other USB boards. It names the board, finds its serial port, reads and writes that port, detects the chip, decodes crash dumps, and flashes firmware with your approval. Bench is free and open source, made by Seaynic Labs.

First five minutes

1. Install it: brew install seayniclabs/tap/bench (see Install).
2. Run bench --doctor. It prints one line per check and a FIX line for each problem.
3. Connect your AI client (see Connect your AI client).
4. Ask it to call bench_modules. It lists the modules that are on and their tools.
5. Plug in a board and ask: "Which boards are connected, and which serial port is each one on?"

Audience and modules

Bench is for developers working with connected hardware. It is one server made of modules. You switch modules on or off. Every module that shipped before 0.4.0 is on by default. A module added in a later release ships off, so you choose to turn it on.

Linux is not in this release. It is planned behind the same tools.

Skills

Skills are short, tested guides for the jobs Bench does. Any app that speaks MCP gets them as prompts (one per skill) and resources (every file in the skill). Apps that read Agent Skills directly load the same skills/ folder.

Tools

25 tools in total. 24 are on by default; decode_crash needs the debug module.

core: ping, bench_modules

usb: list_usb_devices, get_device_info, identify_device, eject_device, hub_topology, tag_device, port_reset, power_info, monitor_events, snapshot_state, diagnose_device, device_descriptors

serial: list_serial_ports, serial_open, serial_read, serial_write, serial_write_and_expect, serial_close, serial_monitor

firmware: chip_detect, flash_firmware

hid: hid_send

debug: decode_crash

Call bench_modules first to see what is on and how to change it.

Settings

All settings are environment variables. Bench starts with an empty environment, and a tool call tells you which variable is missing.

Safety

Bench can change hardware, so some calls are gated.

• Device writes need approval. serial_write, serial_write_and_expect, flash_firmware, port_reset, eject_device, chip_detect (it resets the chip into its bootloader), and hid_send with an action other than get_report or list_reports change a device or its state. Your client asks you through its approval prompt, and the prompt shows the full arguments. A flag from the model, such as confirm: true, does not count as approval.
• Clients that cannot show a prompt are refused. Set BENCH_APPROVE_DEVICE_WRITES=1 in the server's environment to allow writes without a prompt. Only do this when you trust every tool call your AI client makes.
• Every approval is logged. Each request, grant, decline and refusal goes to the approval log. Payloads and file contents are not written there.
• Reads are not gated. Discovery, monitoring, serial reads and serial_monitor, diagnose_device, and crash decoding run without a prompt.
• Local only. Bench makes no network calls and needs no root. Serial access on Linux (future) will need the dialout group, not sudo.

See SECURITY.md for the reporting policy and the list of what Bench touches.

Errors

Every error reads bench.<module>.<code>: <message> Fix: <hint>, for example:

bench.serial.write_not_approved: serial_write changes a device and no approval was given. ... Fix: Set BENCH_APPROVE_DEVICE_WRITES=1 in the server's environment and restart it, or use a client that supports MCP elicitation.

Every tool result also has structuredContent with ok, module, tool and text.

Install

Claude Desktop (MCP Bundle)

Download bench-<version>-darwin-universal.mcpb from the latest release and open it: Claude Desktop shows the install dialog. The bundle carries the binary (Apple Silicon and Intel, macOS 14 or later) and the skills, so it needs neither Homebrew nor Xcode. The binary is ad-hoc signed, not notarized. Check the download against the .sha256 file next to it in the release.

Homebrew

brew install seayniclabs/tap/benchbench --doctor

The formula builds from source with Swift, so it needs Xcode 16.3 or later. It installs the binary as bench and the skills to share/bench/skills, next to it.

Pinned install

Use this when you want exactly the 0.4.3 source, not whatever the formula points at:

git clone --branch v0.4.3 https://github.com/seayniclabs/bench.gitcd benchswift build -c releasecodesign --force --sign - --entitlements Sources/Bench/Bench.entitlements .build/release/Bench.build/release/Bench --doctor

The skills are read from skills/ in the checkout, because the build directory sits inside it.

Claude Code plugin

The repository also packages Bench as a Claude Code plugin (.claude-plugin/plugin.json and .mcp.json): the server and its skills in one install. The plugin runs the bench binary from your PATH, so install Bench with Homebrew first. Then add the Seaynic Labs marketplace and install the plugin:

/plugin marketplace add seayniclabs/plugins/plugin install bench@seayniclabs

Connect your AI client

Bench speaks plain MCP over stdio. Use the full path to the binary in each snippet.

Claude Code

claude mcp add bench -- $(which bench)

Claude Desktop (claude_desktop_config.json)

{  "mcpServers": {    "bench": {      "command": "/absolute/path/to/bench",      "args": []    }  }}

Cursor (~/.cursor/mcp.json)

{  "mcpServers": {    "bench": {      "command": "/absolute/path/to/bench",      "args": []    }  }}

VS Code (.vscode/mcp.json)

{  "servers": {    "bench": {      "type": "stdio",      "command": "/absolute/path/to/bench",      "args": []    }  }}

To set a variable, add an env object next to args, for example "env": { "BENCH_DEBUG_ENABLED": "1" }.

Try these

• "Which boards are connected to this Mac, and which serial port is each one on?"
• "Identify the board on /dev/cu.usbserial-2120 and tell me its exact chip."
• "Bring up my ESP32: confirm the chip, read its boot output, and check it answers ping."
• "My ESP32 keeps rebooting. Decode the crash in this log against build/firmware.elf."
• "Flash build/firmware.bin onto the board with serial number ABC123. Ask me to approve it first."

How it works

Bench uses Apple's IOKit framework to enumerate USB devices. It adds serial port detection (/dev/cu.*), storage details from diskutil, and a built-in database of known maker boards. It talks to your AI tool over stdio using the Model Context Protocol.

AI client  --stdio/JSON-RPC-->  Bench  --IOKit-->      USB device tree                                       --diskutil-->   storage info                                       --/dev/cu.*-->  serial ports                                       --device DB-->  board recognition                                       --addr2line-->  crash decoding (debug module)

Build and test

swift build             # debug buildswift build -c release  # release buildswift test              # unit tests and stdio tests

Bench requires Swift 6.1 or later and targets macOS 14 or later. The tests start the built binary with an empty environment, so run swift build before swift test if you change the server.

The checks that CI and release runs use:

python3 scripts/check_skills.py           # every skill has license, source and credit; no site links in bodiespython3 scripts/tool_lock.py --check      # tool, prompt and instruction text matches the lockpython3 scripts/security_card.py --check  # the security card above is currentpython3 scripts/mcpb_manifest.py --check  # manifest.json lists the tools and prompts the binary servesscripts/pack_mcpb.sh .build/release/Bench dist  # pack the MCP Bundle and check it unpackedpython3 scripts/scan_identifiers.py .     # no private identifiers in the tree

After you change a tool, prompt or the instructions, run python3 scripts/tool_lock.py and python3 scripts/mcpb_manifest.py, and add a changelog line in the same change. After you change the card's inputs, run python3 scripts/security_card.py and paste its output between the card markers.

Changelog

See CHANGELOG.md.

License

MIT. Published by Seaynic Labs. Third-party material is listed in CREDITS.md.

Built by Seaynic Labs. We build tools like this around a business's own systems: local-first, with a person approving every change. See custom integrations.