MCP/mcbluetooth
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcbluetooth/README.md
Ryan Malloy 8cbbcfa286 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
2026-02-02 12:36:17 -07:00

387 lines
16 KiB
Markdown
Raw Blame History

<p align="center">
<pre>
╔╗ ╔╗ ╔╗ ╔╗ ╔╗
║║ ║║ ║║ ╔╗ ║║ ║║
╔╗╔╗╔══╗╔══╗ ║╚═╗║║ ╔╗ ╔╗╔══╝║╔══╗╔═╝║╔══╗╔══╝║╔═╝║╔══╗
║╚╝║║╔═╝║╔╗║ ║╔╗║║║ ║║ ║║║╔══╝║╔╗║║╔╗║║╔╗║║╔╗║║╔╗║║╔╗║
║║║║║╚═╗║╚╝╚╗ ║╚╝║║╚╗║╚═╝║║╚══╗║╚╝║║╚╝║║╚╝║║╚╝║║╚╝║║║║║
╚╩╩╝╚══╝╚═══╝ ╚══╝╚═╝╚═══╝╚═══╝╚══╝╚══╝╚══╝╚══╝╚══╝╚╝╚╝
</pre>
</p>
<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
### 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
```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 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