From 8cbbcfa2864a205a800cec633c5a36fb237cc4e9 Mon Sep 17 00:00:00 2001 From: Ryan Malloy Date: Mon, 2 Feb 2026 12:36:17 -0700 Subject: [PATCH] Overhaul README with comprehensive documentation - Add ASCII art banner and badges - Add example conversation showing real usage - Reorganize features with natural language examples - Complete tools reference with counts (38 total) - Detailed architecture diagram showing all layers - Pairing agent documentation with SSP methods - Requirements table with tested configurations - Development guide with project structure - Roadmap showing completed and planned features --- README.md | 504 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 355 insertions(+), 149 deletions(-) diff --git a/README.md b/README.md index 7858b0a..be4acf2 100644 --- a/README.md +++ b/README.md @@ -1,180 +1,386 @@ -# mcbluetooth +

+ 

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

-A comprehensive MCP server exposing the Linux Bluetooth stack (BlueZ) to LLMs. +

+ Give LLMs control of your Linux Bluetooth stack +

+ +

+ Installation • + Quick Start • + Features • + Tools • + Architecture +

+ +

+ Python 3.11+ + BlueZ 5.x + FastMCP + MIT License +

+ +--- + +**mcbluetooth** is a comprehensive [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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) + +```bash +# Run directly +uvx mcbluetooth + +# Or install globally +uv tool install mcbluetooth +``` + +### From Source + +```bash +git clone https://github.com/yourusername/mcbluetooth +cd mcbluetooth +uv sync +uv run mcbluetooth +``` + +## Quick Start + +### Add to Claude Code + +```bash +# 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: + +```bash +# 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: + +```bash +# Allow btmon without sudo +sudo setcap cap_net_raw+ep /usr/bin/btmon +``` ## Features ### Adapter Management -- List, power, and configure Bluetooth adapters -- Control discoverable and pairable states -- Set adapter aliases +Control your Bluetooth hardware — power, discovery, pairing acceptance. -### 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 . +``` +"Turn on Bluetooth" +"Make my computer discoverable for 2 minutes" +"List all Bluetooth adapters" ``` -## Usage with Claude Code +### Device Discovery & Pairing +Scan for devices with Classic Bluetooth or BLE filters. Smart pairing agent handles PIN codes, numeric comparison, and passkey entry automatically. -```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 +``` +"Scan for nearby Bluetooth devices" +"Pair with the Sony headphones" +"Show me all paired devices" +"Remove the old keyboard from paired devices" ``` -## Requirements +### Audio Control +Full PipeWire/PulseAudio integration for Bluetooth audio devices. -- 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 ``` +"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 -The server exposes dynamic resources for live state queries: +Live state queries without tool calls: | Resource URI | Description | |--------------|-------------| | `bluetooth://adapters` | All Bluetooth adapters | | `bluetooth://paired` | Paired devices | -| `bluetooth://connected` | Connected devices | -| `bluetooth://visible` | All known devices | +| `bluetooth://connected` | Currently connected devices | +| `bluetooth://visible` | All discovered devices | | `bluetooth://trusted` | Trusted devices | -| `bluetooth://adapter/{name}` | Specific adapter details | +| `bluetooth://adapter/{name}` | Specific adapter (e.g., `hci0`) | | `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 | - -### Monitor Tools (btmon integration) -| Tool | Description | -|------|-------------| -| `bt_capture_start` | Start HCI traffic capture to btsnoop file | -| `bt_capture_stop` | Stop a running capture | -| `bt_capture_list_active` | List active captures | -| `bt_capture_parse` | Parse btsnoop file into structured packets | -| `bt_capture_analyze` | Analyze capture with btmon statistics | -| `bt_capture_read_raw` | Read human-readable decoded packets | - -> **Note:** Live capture requires elevated privileges. Run `sudo setcap cap_net_raw+ep /usr/bin/btmon` to enable without sudo. - -## 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 │Monitor │ │ -│ │ Tools │ Tools │ Tools │ Tools │ Tools │ │ -│ └─────────┴─────────┴─────────┴─────────┴────────┘ │ -├─────────────────────────────────────────────────────┤ -│ BlueZ D-Bus Client │ btmon (HCI capture) │ -│ (dbus-fast) │ (btsnoop format) │ -├─────────────────────────────────────────────────────┤ -│ PipeWire/PulseAudio Integration │ -│ (pulsectl-asyncio) │ -└─────────────────────────────────────────────────────┘ +┌─────────────────────────────────────────────────────────────────┐ +│ 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 + +```bash +# 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 + +- [x] Adapter management +- [x] Device discovery and management +- [x] Pairing with Agent1 support +- [x] Audio profiles (A2DP/HFP) +- [x] BLE/GATT operations +- [x] btmon packet capture +- [ ] OBEX file transfer (OPP/FTP) +- [ ] Phonebook access (PBAP) +- [ ] Message access (MAP) +- [ ] Bluetooth Mesh (experimental) + +## Related Projects + +- [FastMCP](https://gofastmcp.com) — The MCP framework powering this server +- [BlueZ](http://www.bluez.org/) — The official Linux Bluetooth stack +- [dbus-fast](https://github.com/bluetooth-devices/dbus-fast) — Fast D-Bus client for Python + ## License -MIT +MIT License — See [LICENSE](LICENSE) for details. + +--- + +

+ Built with FastMCP • Powered by BlueZ • Made for LLMs +