MCP/mcbluetooth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Overhaul README with comprehensive documentation

Browse Source 
- 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
This commit is contained in:
Ryan Malloy 2026-02-02 12:36:17 -07:00
parent 7f3b096c83
commit 8cbbcfa286
1 changed files with 355 additions and 149 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

504
README.md
View File

@ -1,180 +1,386 @@
# mcbluetooth <p align="center">
<pre>
╔╗ ╔╗ ╔╗ ╔╗ ╔╗
║║ ║║ ║║ ╔╗ ║║ ║║
╔╗╔╗╔══╗╔══╗ ║╚═╗║║ ╔╗ ╔╗╔══╝║╔══╗╔═╝║╔══╗╔══╝║╔═╝║╔══╗
║╚╝║║╔═╝║╔╗║ ║╔╗║║║ ║║ ║║║╔══╝║╔╗║║╔╗║║╔╗║║╔╗║║╔╗║║╔╗║
║║║║║╚═╗║╚╝╚╗ ║╚╝║║╚╗║╚═╝║║╚══╗║╚╝║║╚╝║║╚╝║║╚╝║║╚╝║║║║║
╚╩╩╝╚══╝╚═══╝ ╚══╝╚═╝╚═══╝╚═══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚╝╚╝
</pre>
</p>
A comprehensive MCP server exposing the Linux Bluetooth stack (BlueZ) to LLMs. <p align="center">
<strong>Give LLMs control of your Linux Bluetooth stack</strong>
</p>
<p align="center">
<a href="#installation">Installation</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#features">Features</a> •
<a href="#tools-reference">Tools</a> •
<a href="#architecture">Architecture</a>
</p>
<p align="center">
<img src="https://img.shields.io/badge/python-3.11+-blue.svg" alt="Python 3.11+">
<img src="https://img.shields.io/badge/BlueZ-5.x-blue.svg" alt="BlueZ 5.x">
<img src="https://img.shields.io/badge/MCP-FastMCP-green.svg" alt="FastMCP">
<img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT License">
</p>
---
**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 ## Features
### Adapter Management ### Adapter Management
- List, power, and configure Bluetooth adapters Control your Bluetooth hardware — power, discovery, pairing acceptance.
- Control discoverable and pairable states
- Set adapter aliases
### Device Management ```
- Classic Bluetooth and BLE scanning with filters "Turn on Bluetooth"
- Pairing with multi-modal support (elicit, interactive, auto) "Make my computer discoverable for 2 minutes"
- Connect/disconnect/trust/block devices "List all Bluetooth adapters"
- 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 .
``` ```
## 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) "Scan for nearby Bluetooth devices"
claude mcp add mcbluetooth-local -- uv run --directory /path/to/mcbluetooth mcbluetooth "Pair with the Sony headphones"
"Show me all paired devices"
# Or if published to PyPI "Remove the old keyboard from paired devices"
claude mcp add mcbluetooth -- uvx mcbluetooth
``` ```
## 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 ## MCP Resources
The server exposes dynamic resources for live state queries: Live state queries without tool calls:
| Resource URI | Description | | Resource URI | Description |
|--------------|-------------| |--------------|-------------|
| `bluetooth://adapters` | All Bluetooth adapters | | `bluetooth://adapters` | All Bluetooth adapters |
| `bluetooth://paired` | Paired devices | | `bluetooth://paired` | Paired devices |
| `bluetooth://connected` | Connected devices | | `bluetooth://connected` | Currently connected devices |
| `bluetooth://visible` | All known devices | | `bluetooth://visible` | All discovered devices |
| `bluetooth://trusted` | Trusted 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 | | `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 ## Architecture
``` ```
┌─────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
│ FastMCP Server │ │ Claude / LLM │
├─────────────────────────────────────────────────────┤ ├─────────────────────────────────────────────────────────────────┤
│ Tool Categories │ │ MCP Protocol (stdio) │
│ ┌─────────┬─────────┬─────────┬─────────┬────────┐ │ ├─────────────────────────────────────────────────────────────────┤
│ │ Adapter │ Device │ Audio │ BLE │Monitor │ │ │ │
│ │ Tools │ Tools │ Tools │ Tools │ Tools │ │ │ ┌──────────────────── FastMCP Server ──────────────────────┐ │
│ └─────────┴─────────┴─────────┴─────────┴────────┘ │ │ │ │ │
├─────────────────────────────────────────────────────┤ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ BlueZ D-Bus Client │ btmon (HCI capture) │ │ │ │ Adapter │ │ Device │ │ Audio │ │ BLE │ │ │
│ (dbus-fast) │ (btsnoop format) │ │ │ │ Tools │ │ Tools │ │ Tools │ │ Tools │ │ │
├─────────────────────────────────────────────────────┤ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │
│ PipeWire/PulseAudio Integration │ │ │ │ │ │ │ │ │
│ (pulsectl-asyncio) │ │ │ ┌────┴───────────┴───────────┴───────────┴────┐ │ │
└─────────────────────────────────────────────────────┘ │ │ │ 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 ## License
MIT MIT License — See [LICENSE](LICENSE) for details.
---
<p align="center">
Built with FastMCP • Powered by BlueZ • Made for LLMs
</p>