# 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