╔╗  ╔╗         ╔╗               ╔╗  ╔╗
               ║║  ║║         ║║      ╔╗       ║║  ║║
 ╔╗╔╗╔══╗╔══╗  ║╚═╗║║ ╔╗ ╔╗╔══╝║╔══╗╔═╝║╔══╗╔══╝║╔═╝║╔══╗
 ║╚╝║║╔═╝║╔╗║  ║╔╗║║║ ║║ ║║║╔══╝║╔╗║║╔╗║║╔╗║║╔╗║║╔╗║║╔╗║
 ║║║║║╚═╗║╚╝╚╗ ║╚╝║║╚╗║╚═╝║║╚══╗║╚╝║║╚╝║║╚╝║║╚╝║║╚╝║║║║║
 ╚╩╩╝╚══╝╚═══╝ ╚══╝╚═╝╚═══╝╚═══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚╝╚╝
  

Give LLMs control of your Linux Bluetooth stack

Installation • Quick Start • Features • Tools • Architecture

---

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

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?

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

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"

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"

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

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

Total: 38 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  │ │   BLE   │        │  │
│   │  │  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
│   ├── audio.py           # PipeWire/Pulse integration
│   ├── agent.py           # Pairing agent (Agent1)
│   └── tools/
│       ├── adapter.py     # Adapter management
│       ├── device.py      # Device management + pairing
│       ├── audio.py       # Audio profile tools
│       ├── ble.py         # BLE/GATT tools
│       └── monitor.py     # btmon integration
├── tests/
├── pyproject.toml
└── README.md

Roadmap

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

Related Projects

• 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