Introduction

mcbluetooth is a Model Context Protocol (MCP) server that gives LLMs full control over the Linux Bluetooth stack via BlueZ.

What Can You Do?

Ask Claude (or any MCP-compatible LLM) to:

• “Turn on Bluetooth and make my computer discoverable”
• “Scan for devices and pair with my Sony headphones”
• “Connect my headphones and set volume to 80%”
• “Read the battery level from my fitness tracker”
• “Send this PDF to my phone via Bluetooth”
• “Download my phone’s contacts”
• “Enable HFP Audio Gateway and simulate an incoming call”
• “Start capturing Bluetooth traffic for debugging”

Why mcbluetooth?

Natural Language Control

Instead of memorizing bluetoothctl commands or navigating GUI menus, just describe what you want:

"My headphones disconnected, reconnect them and set them as the default audio output"

Complete BlueZ Coverage

mcbluetooth exposes the full power of BlueZ:

• Adapters — Power, discovery, pairing acceptance
• Devices — Scanning, pairing, connection management
• Audio — A2DP/HFP profiles, volume, routing
• HFP Audio Gateway — Phone simulation, call control, indicators
• BLE/GATT — Services, characteristics, notifications
• OBEX — File transfer, phonebook, messages
• Monitoring — HCI packet capture and analysis

Smart Pairing

The built-in pairing agent handles all Bluetooth pairing methods:

Method	Description	Agent Response
Just Works	No user interaction	Auto-accept
Numeric Comparison	Confirm 6-digit code	Interactive or auto
Passkey Entry	Enter code from device	PIN prompt
Legacy PIN	4-6 digit PIN	PIN prompt

MCP Resources

Live state queries without tool calls:

bluetooth://adapters     → All Bluetooth adapters
bluetooth://paired       → Paired devices
bluetooth://connected    → Connected devices
bluetooth://device/AA:BB:CC:DD:EE:FF → Specific device

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     Claude / LLM                            │
├─────────────────────────────────────────────────────────────┤
│                    MCP Protocol (stdio)                     │
├─────────────────────────────────────────────────────────────┤
│                   mcbluetooth (FastMCP)                     │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │ Adapter │ │ Device  │ │  Audio  │ │  OBEX   │  ...      │
│  │  Tools  │ │  Tools  │ │  Tools  │ │  Tools  │           │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘           │
│       └──────────┬┴──────────┬┴───────────┘                │
│         ┌────────┴────────┐  │                              │
│         │  BlueZ D-Bus    │  │  PipeWire/Pulse              │
│         │   (dbus-fast)   │  │  (pulsectl-asyncio)          │
│         └────────┬────────┘  └──────────────────────────────┤
├──────────────────┼──────────────────────────────────────────┤
│                  │                                          │
│           BlueZ (bluetoothd)          obexd                 │
│                  │                                          │
│                Linux Kernel (Bluetooth subsystem)           │
└─────────────────────────────────────────────────────────────┘

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
bluez-obex	Any	For OBEX features (optional)

Next Steps

1. Install mcbluetooth
2. Try the quick start guide
3. Explore the tool reference