mcbluetooth

A comprehensive MCP server that exposes the Linux Bluetooth stack to LLMs. Control adapters, pair devices, manage audio, read BLE sensors, and transfer files — all through natural language.

Get Started View on GitHub

Features

Full BlueZ Integration

Adapters, devices, pairing, audio profiles, and BLE/GATT — the complete Linux Bluetooth stack at your fingertips.

Smart Pairing Agent

Handles PIN codes, passkeys, and numeric comparison automatically. Supports interactive, auto, and elicitation modes.

Audio Control

PipeWire and PulseAudio integration for seamless Bluetooth audio management. Switch profiles, adjust volume, set defaults.

OBEX Profiles

File transfer (OPP/FTP), phonebook access (PBAP), and message access (MAP) for connected phones and devices.

BLE & GATT

Read sensors, write commands, subscribe to notifications. Full support for Bluetooth Low Energy devices.

Protocol Analysis

Capture and analyze Bluetooth traffic with btmon integration. Debug connections and reverse engineer protocols.

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?

# Run directly
uvx mcbluetooth

# Or install globally
uv tool install mcbluetooth

git clone https://github.com/yourusername/mcbluetooth
cd mcbluetooth
uv sync
uv run mcbluetooth

Add to Claude Code

claude mcp add mcbluetooth -- uvx mcbluetooth

Tool Categories

Category	Tools	Description
Adapter	6	Power, discoverable, pairable, alias
Device	12	Scan, pair, connect, trust, block
Audio	7	Profiles, volume, mute, default sink
BLE	7	GATT services, characteristics, notify
Monitor	6	HCI capture, parse, analyze
OBEX	23	File transfer, phonebook, messages
Total	61	Complete Bluetooth control