Ryan Malloy
013cd0eb2f
Comprehensive BlueZ MCP server exposing Linux Bluetooth stack to LLMs: - Adapter management (list, power, discoverable, pairable) - Device discovery and management (scan, pair, connect, trust) - Audio profiles with PipeWire/PulseAudio integration (A2DP/HFP switching) - BLE/GATT support (services, characteristics, read/write/notify) Built on: - FastMCP 2.14.4 for MCP protocol - dbus-fast 4.0.0 for async BlueZ D-Bus communication - pulsectl-asyncio 1.2.2 for audio control
155 lines
5.0 KiB
Markdown
155 lines
5.0 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 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 |
|
|
|
|
## 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 │ │
|
|
│ │ Tools │ Tools │ Tools │ Tools │ │
|
|
│ └─────────┴─────────┴─────────┴─────────┘ │
|
|
├─────────────────────────────────────────────┤
|
|
│ BlueZ D-Bus Client Layer │
|
|
│ (dbus-fast) │
|
|
├─────────────────────────────────────────────┤
|
|
│ PipeWire/PulseAudio Integration │
|
|
│ (pulsectl-asyncio) │
|
|
└─────────────────────────────────────────────┘
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|