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.
181 lines
6.3 KiB
Markdown
181 lines
6.3 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# Install with uv (recommended)
|
|
uvx mcbluetooth
|
|
|
|
# Or install from source
|
|
uv pip install -e .
|
|
```
|
|
|
|
## Usage with Claude Code
|
|
|
|
```bash
|
|
# 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 `bluetooth` group or have polkit permissions
|
|
|
|
### Permissions
|
|
|
|
```bash
|
|
# 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/btmon` to 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
|