mcbluetooth

Give LLMs control of your Linux Bluetooth stack

Documentation • Installation • Quick Start • Features • Tools

---

mcbluetooth is a comprehensive Model Context Protocol (MCP) server that exposes the Linux Bluetooth stack to LLMs. Ask Claude to scan for devices, pair your headphones, adjust volume, read BLE sensors, or capture Bluetooth traffic — all through natural language.

Why mcbluetooth?

• Natural Language Control — "Connect to my headphones and set volume to 80%"
• Full BlueZ Integration — Adapters, devices, pairing, audio profiles, BLE/GATT
• Smart Pairing Agent — Handles PIN codes, passkeys, and confirmations automatically
• Protocol Analysis — Capture and analyze Bluetooth traffic with btmon integration
• Audio Intelligence — PipeWire/PulseAudio integration for seamless audio control
• HFP Audio Gateway — Act as a phone for headset testing and call simulation
• OBEX Profiles — File transfer, phonebook access, and message access
• BLE Discovery — Enumerate GATT services, read characteristics, decode sensor data
• Device Fingerprinting — Identify devices by their advertised services and behaviors
• Security Research — Test pairing modes, analyze HCI traffic, probe unknown devices

Example Conversation

You: Scan for Bluetooth devices and connect to my Bose headphones

Claude: I'll scan for nearby Bluetooth devices.

[Calling bt_scan with adapter="hci0", timeout=10, mode="both"]

Found 5 devices:
  • Bombay (C8:7B:23:55:68:E8) - Bose NCH700, paired
  • DS18 BT-TWO (20:23:05:26:02:31) - Audio device
  • iPhone (AA:BB:CC:DD:EE:FF) - Phone
  ...

I found your Bose headphones "Bombay". Connecting now...

[Calling bt_connect with adapter="hci0", address="C8:7B:23:55:68:E8"]

✓ Connected to Bombay! The headphones are ready. Would you like me
  to set them as the default audio output?

Discovery & Reverse Engineering

mcbluetooth shines when exploring unknown Bluetooth devices:

You: Scan for BLE devices and show me what services that fitness tracker advertises

Claude: I found a device "Mi Band 7" at E4:12:5C:AA:BB:CC. Let me enumerate its GATT services...

The device exposes:
- 0x180D Heart Rate Service (standard)
- 0x180F Battery Service (standard)
- 0xFEE0 Xiaomi proprietary service (likely firmware/auth)
- 0xFEE1 Xiaomi proprietary service (likely sensor data)

The heart rate characteristic (0x2A37) supports notifications.
Want me to subscribe and capture some readings?

Common workflows:

Use Case	What Claude Can Do
BLE Sensor Reverse Engineering	Enumerate services, read/write characteristics, decode data formats
Device Fingerprinting	Identify manufacturer, capabilities, and protocols from advertisements
Protocol Analysis	Capture HCI traffic with btmon, analyze pairing handshakes
Pairing Mode Testing	Test all 4 SSP modes (Just Works, Numeric, Passkey, Legacy PIN)
HFP Headset Testing	Simulate phone calls, send AT commands, test audio routing
Service Discovery	Find hidden services, probe for undocumented characteristics

Installation

Using uvx (recommended)

# Run directly
uvx mcbluetooth

# Or install globally
uv tool install mcbluetooth

From Source

git clone https://github.com/yourusername/mcbluetooth
cd mcbluetooth
uv sync
uv run mcbluetooth

Quick Start

Add to Claude Code

# From PyPI
claude mcp add mcbluetooth -- uvx mcbluetooth

# From source
claude mcp add mcbluetooth -- uv run --directory /path/to/mcbluetooth mcbluetooth

Permissions Setup

mcbluetooth needs access to the BlueZ D-Bus interface:

# Option 1: Add user to bluetooth group (requires re-login)
sudo usermod -aG bluetooth $USER

# Option 2: Run with current permissions (if polkit is configured)
# Most desktop Linux distributions allow this by default

For HCI packet capture (btmon), additional permissions are needed:

# Allow btmon without sudo
sudo setcap cap_net_raw+ep /usr/bin/btmon

OBEX Setup (for file transfer, phonebook, messages)

OBEX features require the obexd daemon:

# Install obexd (if not included with BlueZ)
# Arch Linux
sudo pacman -S bluez-obex

# Debian/Ubuntu
sudo apt install bluez-obex

# Check status
bt_obex_status  # Use this tool to verify setup

The bt_obex_status tool will check if obexd is installed and running, and provide guidance if setup is needed.

Features

Adapter Management

Control your Bluetooth hardware — power, discovery, pairing acceptance.

"Turn on Bluetooth"
"Make my computer discoverable for 2 minutes"
"List all Bluetooth adapters"

Device Discovery & Pairing

Scan for devices with Classic Bluetooth or BLE filters. Smart pairing agent handles PIN codes, numeric comparison, and passkey entry automatically.

"Scan for nearby Bluetooth devices"
"Pair with the Sony headphones"
"Show me all paired devices"
"Remove the old keyboard from paired devices"

Audio Control

Full PipeWire/PulseAudio integration for Bluetooth audio devices.

"Connect my headphones and set them as default output"
"Switch to HFP mode for a phone call"
"Set headphone volume to 70%"
"Mute Bluetooth audio"

BLE / GATT

Interact with Bluetooth Low Energy devices — read sensors, write commands, subscribe to notifications.

"Connect to my fitness tracker and read the battery level"
"List all GATT services on the heart rate monitor"
"Read the temperature from the BLE thermometer"
"Subscribe to heart rate notifications"

HFP Audio Gateway

Act as a phone (Audio Gateway) for testing Bluetooth headsets. Simulate calls, control volume, and update status indicators over the HFP AT command protocol.

"Enable HFP Audio Gateway mode"
"Simulate an incoming call to the connected headset"
"Set the headset speaker volume to 12"
"Update the battery indicator to level 3"

Protocol Analysis

Capture and analyze Bluetooth traffic for debugging and reverse engineering.

"Start capturing Bluetooth traffic"
"Show me the last 50 HCI packets"
"Analyze the capture file for errors"

OBEX File Transfer

Send files, browse phone storage, and download photos using OBEX profiles.

"Send this PDF to my phone"
"Browse the files on my phone's storage"
"Download all photos from DCIM folder"

Phonebook & Messages

Access contacts and SMS messages from connected phones via PBAP and MAP profiles.

"Download my phone's contacts"
"Search for John in the phonebook"
"List unread text messages"

Tools Reference

Adapter Tools (6)

Tool	Description
bt_list_adapters	List all Bluetooth adapters with status
bt_adapter_info	Get detailed adapter properties
bt_adapter_power	Power adapter on/off
bt_adapter_discoverable	Set discoverable state and timeout
bt_adapter_pairable	Enable/disable pairing acceptance
bt_adapter_set_alias	Set adapter friendly name

Device Tools (12)

Tool	Description
bt_scan	Scan for devices (classic/BLE/both)
bt_list_devices	List known devices with filters
bt_device_info	Get device properties and services
bt_device_set_alias	Set device friendly name
bt_pair	Initiate pairing with agent support
bt_pair_confirm	Confirm/reject pending pairing request
bt_pairing_status	Check for pending pairing requests
bt_unpair	Remove device and pairing info
bt_connect	Connect to paired device
bt_disconnect	Disconnect active connection
bt_trust	Set device trust status
bt_block	Block/unblock device

Audio Tools (7)

Tool	Description
bt_audio_list	List audio devices with profiles
bt_audio_connect	Connect audio profiles
bt_audio_disconnect	Disconnect audio
bt_audio_set_profile	Switch A2DP/HFP/HSP/off
bt_audio_set_default	Set as default audio sink
bt_audio_volume	Set volume (0-150%)
bt_audio_mute	Mute/unmute audio

HFP Audio Gateway Tools (8)

Tool	Description
bt_hfp_ag_enable	Register HFP AG profile with BlueZ
bt_hfp_ag_disable	Unregister HFP AG profile
bt_hfp_ag_status	Get AG connections, SLC state, indicators
bt_hfp_ag_simulate_call	Simulate incoming call (RING + CLIP)
bt_hfp_ag_end_call	Terminate call from AG side
bt_hfp_ag_set_volume	Set speaker or microphone volume (0-15)
bt_hfp_ag_set_signal	Update signal strength indicator (0-5)
bt_hfp_ag_set_battery	Update battery level indicator (0-5)

BLE Tools (7)

Tool	Description
bt_ble_scan	BLE-specific scan with filters
bt_ble_services	List GATT services
bt_ble_characteristics	List service characteristics
bt_ble_read	Read characteristic value
bt_ble_write	Write characteristic value
bt_ble_notify	Enable/disable notifications
bt_ble_battery	Read standard battery level

Monitor Tools (6)

Tool	Description
bt_capture_start	Start HCI traffic capture
bt_capture_stop	Stop running capture
bt_capture_list_active	List active captures
bt_capture_parse	Parse btsnoop to structured data
bt_capture_analyze	Statistical analysis of capture
bt_capture_read_raw	Human-readable packet decode

OBEX Tools (23)

Setup & Session Management

Tool	Description
bt_obex_status	Check obexd daemon status and requirements
bt_obex_start_daemon	Start the obexd daemon
bt_obex_connect	Create OBEX session (OPP/FTP/PBAP/MAP)
bt_obex_disconnect	Close OBEX session
bt_obex_sessions	List active OBEX sessions

Object Push (OPP)

Tool	Description
bt_obex_send_file	Send file to device
bt_obex_get_vcard	Pull business card from device

File Transfer (FTP)

Tool	Description
bt_obex_browse	List files/folders on device
bt_obex_get	Download file from device
bt_obex_put	Upload file to device
bt_obex_delete	Delete file/folder on device
bt_obex_mkdir	Create folder on device

Phonebook Access (PBAP)

Tool	Description
bt_phonebook_pull	Download entire phonebook
bt_phonebook_list	List phonebook entries
bt_phonebook_get	Download single contact
bt_phonebook_search	Search phonebook
bt_phonebook_count	Count phonebook entries

Message Access (MAP)

Tool	Description
bt_messages_folders	List message folders
bt_messages_list	List messages in folder
bt_messages_get	Download message content
bt_messages_send	Send SMS via MAP

Transfer Management

Tool	Description
bt_obex_transfer_status	Check transfer progress
bt_obex_transfer_cancel	Cancel active transfer

Total: 69 tools

MCP Resources

Live state queries without tool calls:

Resource URI	Description
bluetooth://adapters	All Bluetooth adapters
bluetooth://paired	Paired devices
bluetooth://connected	Currently connected devices
bluetooth://visible	All discovered devices
bluetooth://trusted	Trusted devices
bluetooth://adapter/{name}	Specific adapter (e.g., hci0)
bluetooth://device/{address}	Specific device details

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        Claude / LLM                              │
├─────────────────────────────────────────────────────────────────┤
│                     MCP Protocol (stdio)                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌──────────────────── FastMCP Server ──────────────────────┐  │
│   │                                                           │  │
│   │  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐│
│   │  │ Adapter │ │ Device  │ │Audio/HFP│ │   BLE   │ │  OBEX   ││
│   │  │  Tools  │ │  Tools  │ │  Tools  │ │  Tools  │ │  Tools  ││
│   │  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘│
│   │       │           │           │           │              │  │
│   │  ┌────┴───────────┴───────────┴───────────┴────┐        │  │
│   │  │           Pairing Agent (Agent1)            │        │  │
│   │  └─────────────────────────────────────────────┘        │  │
│   │                                                           │  │
│   │  ┌─────────────────┐  ┌──────────────────────────┐      │  │
│   │  │  Monitor Tools  │  │    Resource Providers    │      │  │
│   │  └────────┬────────┘  └──────────────────────────┘      │  │
│   │           │                                              │  │
│   └───────────┼──────────────────────────────────────────────┘  │
│               │                                                  │
├───────────────┼──────────────────────────────────────────────────┤
│               │                                                  │
│  ┌────────────┴────────────┐    ┌─────────────────────────────┐ │
│  │   BlueZ D-Bus Client    │    │   PipeWire / PulseAudio     │ │
│  │      (dbus-fast)        │    │    (pulsectl-asyncio)       │ │
│  └────────────┬────────────┘    └──────────────┬──────────────┘ │
│               │                                 │                │
├───────────────┼─────────────────────────────────┼────────────────┤
│               │                                 │                │
│  ┌────────────┴────────────┐    ┌──────────────┴──────────────┐ │
│  │     BlueZ (bluetoothd)  │    │      btmon (HCI capture)    │ │
│  │        D-Bus API        │    │       btsnoop format        │ │
│  └─────────────────────────┘    └─────────────────────────────┘ │
│                                                                  │
│                        Linux Kernel                              │
│                    (Bluetooth subsystem)                         │
└─────────────────────────────────────────────────────────────────┘

Pairing Agent

mcbluetooth implements the full BlueZ org.bluez.Agent1 interface for handling pairing operations:

Pairing Method	Description	Agent Callback
Just Works	No user interaction	RequestAuthorization
Numeric Comparison	Confirm 6-digit code matches	RequestConfirmation
Passkey Entry	Enter code shown on other device	RequestPasskey
Legacy PIN	Enter 4-6 digit PIN	RequestPinCode

Pairing modes:

• interactive (default) — Returns pending status, use bt_pair_confirm to respond
• auto — Automatically accepts all pairings (use in trusted environments)
• elicit — Uses MCP elicitation for direct user prompts (if client supports)

Requirements

Requirement	Version	Notes
Linux	Any	BlueZ is Linux-only
Python	3.11+	Async/await, type hints
BlueZ	5.x	Bluetooth daemon
PipeWire or PulseAudio	Any	For audio features

Tested Configurations

• Arch Linux + BlueZ 5.85 + PipeWire 1.4
• Ubuntu 22.04 + BlueZ 5.64 + PulseAudio
• Fedora 39 + BlueZ 5.70 + PipeWire

Development

# Clone and setup
git clone https://github.com/yourusername/mcbluetooth
cd mcbluetooth
uv sync

# Run tests
uv run pytest

# Lint
uv run ruff check src/

# Run server locally
uv run mcbluetooth

Project Structure

mcbluetooth/
├── src/mcbluetooth/
│   ├── __init__.py
│   ├── server.py          # FastMCP server entry point
│   ├── dbus_client.py     # BlueZ D-Bus wrapper
│   ├── obex_client.py     # obexd D-Bus wrapper
│   ├── audio.py           # PipeWire/Pulse integration
│   ├── agent.py           # Pairing agent (Agent1)
│   ├── hfp_ag.py          # HFP Audio Gateway (Profile1)
│   └── tools/
│       ├── adapter.py     # Adapter management
│       ├── device.py      # Device management + pairing
│       ├── audio.py       # Audio profile tools
│       ├── hfp.py         # HFP AG call simulation
│       ├── ble.py         # BLE/GATT tools
│       ├── monitor.py     # btmon integration
│       └── obex.py        # OBEX profile tools
├── tests/
├── pyproject.toml
└── README.md

Roadmap

• Adapter management
• Device discovery and management
• Pairing with Agent1 support
• Audio profiles (A2DP/HFP)
• HFP Audio Gateway (call simulation, indicators)
• BLE/GATT operations
• btmon packet capture
• OBEX file transfer (OPP/FTP)
• Phonebook access (PBAP)
• Message access (MAP)
• Bluetooth Mesh (experimental)

Related Projects

• mcbluetooth-esp32 — ESP32 test harness for automated E2E Bluetooth testing with mcbluetooth
• FastMCP — The MCP framework powering this server
• BlueZ — The official Linux Bluetooth stack
• dbus-fast — Fast D-Bus client for Python

License

MIT License — See LICENSE for details.

---

Built with FastMCP • Powered by BlueZ • Made for LLMs