Ryan Malloy
9d1c0f3e0f
23-page docs site following diataxis principles with guides, reference, and explanation sections covering all 61 MCP tools. Bluetooth-themed design with Pagefind search.
4.9 KiB
4.9 KiB
| title | description |
|---|---|
| Introduction | What is mcbluetooth and why use it? |
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"
- "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
- 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) |