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 |
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