Ryan Malloy
cd03fa9253
New monitor tools: - bt_capture_start: Start background HCI capture to btsnoop file - bt_capture_stop: Stop running capture by ID - bt_capture_list_active: List active captures - bt_capture_parse: Parse btsnoop into structured packet data - bt_capture_analyze: Run btmon analysis on capture file - bt_capture_read_raw: Read decoded packets via btmon Features: - Native btsnoop file parsing (no btmon needed for parse) - Filter by packet type (HCI_CMD, ACL_DATA, HCI_EVENT, etc.) - Filter by direction (TX/RX) - Statistics and hex dump output Note: Live capture requires CAP_NET_RAW or sudo.
mcbluetooth
A comprehensive MCP server exposing the Linux Bluetooth stack (BlueZ) to LLMs.
Features
Adapter Management
- List, power, and configure Bluetooth adapters
- Control discoverable and pairable states
- Set adapter aliases
Device Management
- Classic Bluetooth and BLE scanning with filters
- Pairing with multi-modal support (elicit, interactive, auto)
- Connect/disconnect/trust/block devices
- View device properties including RSSI, UUIDs, manufacturer data
Audio Profiles (A2DP/HFP)
- List audio devices (sinks, sources, cards)
- Connect/disconnect audio profiles
- Switch between A2DP (high quality) and HFP (calls with mic)
- Volume control and muting
- Set default audio device (PipeWire/PulseAudio integration)
Bluetooth Low Energy (BLE)
- BLE-specific scanning with name/service filters
- GATT service discovery
- Read/write characteristics
- Enable/disable notifications
- Battery level reading (standard Battery Service)
Installation
# Install with uv (recommended)
uvx mcbluetooth
# Or install from source
uv pip install -e .
Usage with Claude Code
# Add to Claude Code (from source)
claude mcp add mcbluetooth-local -- uv run --directory /path/to/mcbluetooth mcbluetooth
# Or if published to PyPI
claude mcp add mcbluetooth -- uvx mcbluetooth
Requirements
- Linux with BlueZ 5.x
- Python 3.11+
- PipeWire or PulseAudio (for audio features)
- User must be in
bluetoothgroup or have polkit permissions
Permissions
# Add user to bluetooth group
sudo usermod -aG bluetooth $USER
# Or configure polkit for BlueZ D-Bus access
MCP Resources
The server exposes dynamic resources for live state queries:
| Resource URI | Description |
|---|---|
bluetooth://adapters |
All Bluetooth adapters |
bluetooth://paired |
Paired devices |
bluetooth://connected |
Connected devices |
bluetooth://visible |
All known devices |
bluetooth://trusted |
Trusted devices |
bluetooth://adapter/{name} |
Specific adapter details |
bluetooth://device/{address} |
Specific device details |
MCP Tools
Adapter Tools
| Tool | Description |
|---|---|
bt_list_adapters |
List all Bluetooth adapters |
bt_adapter_info |
Get adapter details |
bt_adapter_power |
Power on/off |
bt_adapter_discoverable |
Set visible to other devices |
bt_adapter_pairable |
Enable/disable pairing acceptance |
bt_adapter_set_alias |
Set friendly name |
Device Tools
| Tool | Description |
|---|---|
bt_scan |
Scan for devices (classic/BLE/both) |
bt_list_devices |
List known devices with filters |
bt_device_info |
Get device details |
bt_pair |
Initiate pairing |
bt_pair_confirm |
Confirm/reject pairing |
bt_unpair |
Remove device |
bt_connect |
Connect to paired device |
bt_disconnect |
Disconnect device |
bt_trust |
Trust/untrust device |
bt_block |
Block/unblock device |
Audio Tools
| Tool | Description |
|---|---|
bt_audio_list |
List all audio devices |
bt_audio_connect |
Connect audio profiles |
bt_audio_disconnect |
Disconnect audio |
bt_audio_set_profile |
Switch A2DP/HFP/off |
bt_audio_set_default |
Set as default sink |
bt_audio_volume |
Set volume (0-150) |
bt_audio_mute |
Mute/unmute |
BLE Tools
| Tool | Description |
|---|---|
bt_ble_scan |
BLE scan with filters |
bt_ble_services |
List GATT services |
bt_ble_characteristics |
List characteristics |
bt_ble_read |
Read characteristic value |
bt_ble_write |
Write characteristic value |
bt_ble_notify |
Enable/disable notifications |
bt_ble_battery |
Read battery level |
Monitor Tools (btmon integration)
| Tool | Description |
|---|---|
bt_capture_start |
Start HCI traffic capture to btsnoop file |
bt_capture_stop |
Stop a running capture |
bt_capture_list_active |
List active captures |
bt_capture_parse |
Parse btsnoop file into structured packets |
bt_capture_analyze |
Analyze capture with btmon statistics |
bt_capture_read_raw |
Read human-readable decoded packets |
Note: Live capture requires elevated privileges. Run
sudo setcap cap_net_raw+ep /usr/bin/btmonto enable without sudo.
Example Prompts
# Discover and connect headphones
"Scan for Bluetooth devices and connect to my Sony headphones"
# Switch audio profile for calls
"Switch my headphones to HFP mode for a phone call"
# Read from a fitness tracker
"Connect to my fitness band and read the battery level"
# Set up audio output
"List all Bluetooth audio devices and set my speaker as the default"
Architecture
┌─────────────────────────────────────────────────────┐
│ FastMCP Server │
├─────────────────────────────────────────────────────┤
│ Tool Categories │
│ ┌─────────┬─────────┬─────────┬─────────┬────────┐ │
│ │ Adapter │ Device │ Audio │ BLE │Monitor │ │
│ │ Tools │ Tools │ Tools │ Tools │ Tools │ │
│ └─────────┴─────────┴─────────┴─────────┴────────┘ │
├─────────────────────────────────────────────────────┤
│ BlueZ D-Bus Client │ btmon (HCI capture) │
│ (dbus-fast) │ (btsnoop format) │
├─────────────────────────────────────────────────────┤
│ PipeWire/PulseAudio Integration │
│ (pulsectl-asyncio) │
└─────────────────────────────────────────────────────┘
License
MIT