MCP/mcbluetooth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcbluetooth/README.md
Ryan Malloy b0aa6434ae Add production docs deployment 
- Add Dockerfile with multi-stage build (node -> caddy)
- Add docker-compose.yml for caddy-docker-proxy
- Update astro.config.mjs with production site URL
- Add Documentation link to README.md header
- Add Documentation URL to pyproject.toml
2026-02-10 17:08:10 -07:00

526 lines
20 KiB
Markdown
Raw Blame History

<h1 align="center">mcbluetooth</h1>
<p align="center">
<strong>Give LLMs control of your Linux Bluetooth stack</strong>
</p>
<p align="center">
<a href="https://mcbluetooth.supported.systems">Documentation</a> •
<a href="#installation">Installation</a> •
<a href="#quick-start">Quick Start</a> •
<a href="#features">Features</a> •
<a href="#tools-reference">Tools</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
- **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)
```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
```
### OBEX Setup (for file transfer, phonebook, messages)
OBEX features require the `obexd` daemon:
```bash
# 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
```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
│ ├── 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
- [x] Adapter management
- [x] Device discovery and management
- [x] Pairing with Agent1 support
- [x] Audio profiles (A2DP/HFP)
- [x] HFP Audio Gateway (call simulation, indicators)
- [x] BLE/GATT operations
- [x] btmon packet capture
- [x] OBEX file transfer (OPP/FTP)
- [x] Phonebook access (PBAP)
- [x] Message access (MAP)
- [ ] Bluetooth Mesh (experimental)
## Related Projects
- [mcbluetooth-esp32](https://git.supported.systems/MCP/mcbluetooth-esp32) — ESP32 test harness for automated E2E Bluetooth testing with mcbluetooth
- [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 License — See [LICENSE](LICENSE) for details.
---
<p align="center">
Built with FastMCP • Powered by BlueZ • Made for LLMs
</p>
Reference in New Issue View Git Blame Copy Permalink