Bench는 Claude Code, Cursor, Windsurf와 같은 AI 도구가 연결된 USB 하드웨어를 인식할 수 있도록 지원하는 네이티브 macOS MCP 서버입니다. 장치를 식별하고, 직렬 포트를 찾으며, 일반적인 메이커 보드를 인식하여 AI 어시스턴트가 작업대 위에 무엇이 있는지 알 수 있게 합니다.

API 키도, 드라이버도 필요 없습니다. 명령어 한 줄로 설치하세요.

기능

4개 카테고리에 걸친 22가지 도구:

검색 (Discovery)

도구	설명
`ping`	상태 확인 — 서버 상태, 버전, macOS 버전 반환
`list_usb_devices`	공급업체, 유형, 속도, 일련번호를 포함하여 연결된 모든 USB 장치 나열
`get_device_info`	일련번호, 위치 ID 또는 이름으로 특정 장치에 대한 상세 정보 확인
`identify_device`	83개 이상의 알려진 메이커/개발 보드 스마트 식별
`list_serial_ports`	USB 장치 매칭을 포함한 직렬 포트 열거
`hub_topology`	포트 계층 구조 및 연결을 보여주는 USB 허브 트리 뷰
`device_descriptors`	전체 USB 디스크립터 체인 — 인터페이스, 엔드포인트, 클래스 코드
`chip_detect`	esptool을 통해 ESP32/마이크로컨트롤러의 정확한 칩 유형 감지

모니터링 (Monitoring)

도구	설명
`monitor_events`	호출 간 USB 연결/연결 해제 이벤트 감지
`snapshot_state`	USB 장치 상태 스냅샷 캡처 및 비교
`diagnose_device`	특정 장치의 USB 오류에 대한 시스템 로그 쿼리
`power_info`	장치별 전력 소모량, 버스 예산, 충전 감지

관리 (Management)

도구	설명
`eject_device`	이동식 저장 장치를 안전하게 마운트 해제 및 제거
`tag_device`	장치에 대한 사용자 정의 별칭 지정
`port_reset`	USB 포트를 재설정하여 멈춘 장치 복구
`flash_firmware`	esptool/dfu-util/avrdude/UF2를 통한 펌웨어 플래싱
`hid_send`	원시 HID 리포트 송수신

직렬 통신 (Serial Communication)

도구	설명
`serial_open`	구성 가능한 보드 레이트, 데이터 비트, 패리티로 직렬 연결 열기
`serial_read`	열린 직렬 연결에서 사용 가능한 데이터 읽기
`serial_write`	열린 직렬 연결에 데이터 또는 명령 쓰기
`serial_close`	열린 직렬 연결 닫기
`serial_monitor`	N초 동안 직렬 출력 캡처 (부팅 로그, 디버그 출력)

특징

장치 분류 — 장치를 저장 장치, 입력 장치, 허브, 비디오, 직렬 어댑터, 마이크로컨트롤러 또는 디버거로 자동 분류
직렬 포트 감지 — USB 장치를 /dev/cu.* 직렬 포트에 매핑 (메이커들의 가장 흔한 질문)
83개 이상의 알려진 보드 — Arduino, Raspberry Pi, ESP32, Adafruit, SparkFun, Teensy, STM32 및 일반적인 USB-직렬 칩 인식
저장 장치 정보 — USB 드라이브의 마운트 지점, 용량 및 여유 공간 확인
USB 모니터링 — 이벤트 추적, 상태 스냅샷, 진단 로그 쿼리 및 전력 분석
펌웨어 플래싱 — ESP32, STM32, Arduino AVR 및 RP2040 보드 직접 플래싱
HID 상호작용 — Stream Deck, 매크로 패드 및 사용자 정의 HID 장치에서 리포트 송수신
직렬 통신 — 구성 가능한 보드 레이트, 데이터 비트, 패리티 및 정지 비트로 직렬 포트 열기, 읽기, 쓰기 및 모니터링

요구 사항

macOS 14 이상 (Sonoma 이상), Apple Silicon
MCP 호환 AI 도구 (Claude Code, Cursor, Windsurf 등)
소스에서 빌드 시: Xcode 16.3+ / Swift 6.1+

설치

Homebrew (권장)

brew install seayniclabs/tap/bench

소스에서 빌드

git clone https://github.com/seayniclabs/bench.git
cd bench
swift build -c release
codesign --force --sign - --entitlements Sources/Bench/Bench.entitlements .build/release/Bench

바이너리는 .build/release/Bench에 있습니다.

Claude Code에 추가

claude mcp add bench -- $(which bench)

또는 ~/.claude.json에 수동으로 추가:

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

사용법

연결 후 AI 도구에 다음과 같이 질문하세요:

"어떤 USB 장치가 연결되어 있니?"
"내 Arduino가 어떤 포트에 연결되어 있니?"
"/dev/cu.usbserial-2120에 있는 장치를 식별해줘"
"Samsung T7을 꺼내줘"
"모든 저장 장치를 보여줘"
"/dev/cu.usbserial-2120에 9600 보드 레이트로 직렬 연결을 열어줘"
"내 ESP32의 직렬 출력을 10초 동안 모니터링해줘"

작동 원리

Bench는 Apple의 IOKit 프레임워크를 사용하여 macOS에서 USB 장치를 네이티브로 열거합니다. 직렬 포트 감지(/dev/cu.* 스캔), 저장 장치 정보(diskutil) 및 내장된 알려진 메이커 보드 데이터베이스를 통해 결과를 보강합니다. Model Context Protocol(JSON-RPC)을 사용하여 stdio를 통해 AI 도구와 통신합니다.

AI Tool  --stdio/JSON-RPC-->  Bench  --IOKit-->  USB Device Tree
                                     --diskutil-->  Storage Info
                                     --/dev/cu.*-->  Serial Ports
                                     --DeviceDB-->  Board Recognition

특별한 권한은 필요하지 않습니다. IOKit USB 열거는 CLI 바이너리에서 권한 없이 작동합니다.

빌드

swift build             # debug build
swift build -c release  # release build
swift test              # run tests

Bench는 Swift 6.1 이상이 필요하며 macOS 14 이상을 대상으로 합니다.

라이선스

MIT

크레딧

Seaynic Labs에서 제작.

Bench

기능