Skip to content
mcbluetooth

Quick Start

import { Steps, Aside } from ‘@astrojs/starlight/components’;

This guide walks you through basic Bluetooth operations with mcbluetooth.

Prerequisites

Section titled “Prerequisites”
  • mcbluetooth installed and added to Claude Code
  • A Bluetooth adapter (built-in or USB dongle)
  • A Bluetooth device to test with (headphones, phone, etc.)

Basic Operations

Section titled “Basic Operations”

  1. Check your adapter

    bt_list_adapters

    You should see your Bluetooth adapter:

    [{"name": "hci0", "address": "...", "powered": true, ...}]

  2. Power on Bluetooth (if needed)

    bt_adapter_power adapter="hci0" on=true

  3. Scan for devices

    bt_scan adapter="hci0" timeout=10 mode="both"

    This scans for 10 seconds and returns all discovered devices.

  4. Pair with a device

    Put your device in pairing mode, then:

    bt_pair adapter="hci0" address="AA:BB:CC:DD:EE:FF"

    The agent handles PIN/passkey automatically for most devices.

  5. Connect to the paired device

    bt_connect adapter="hci0" address="AA:BB:CC:DD:EE:FF"

Common Workflows

Section titled “Common Workflows”

Connect Headphones

Section titled “Connect Headphones”
# Scan for devices
bt_scan adapter="hci0"


# Pair (first time only)
bt_pair adapter="hci0" address="C8:7B:23:55:68:E8"


# Connect
bt_connect adapter="hci0" address="C8:7B:23:55:68:E8"


# Set as default audio and adjust volume
bt_audio_set_default address="C8:7B:23:55:68:E8"
bt_audio_volume address="C8:7B:23:55:68:E8" volume=75

Read a BLE Sensor

Section titled “Read a BLE Sensor”
# Scan for BLE devices
bt_ble_scan adapter="hci0" timeout=10


# Connect and discover services
bt_connect adapter="hci0" address="AA:BB:CC:DD:EE:FF"
bt_ble_services adapter="hci0" address="AA:BB:CC:DD:EE:FF"


# Read battery level (standard BLE service)
bt_ble_battery adapter="hci0" address="AA:BB:CC:DD:EE:FF"


# Read a specific characteristic
bt_ble_read adapter="hci0" address="AA:BB:CC:DD:EE:FF" char_uuid="00002a19-0000-1000-8000-00805f9b34fb"

Send a File to Your Phone

Section titled “Send a File to Your Phone”
# Check OBEX is ready
bt_obex_status


# Send file (phone will show accept prompt)
bt_obex_send_file address="AA:BB:CC:DD:EE:FF" file_path="~/Documents/report.pdf"

Download Contacts from Phone

Section titled “Download Contacts from Phone”
# Pull entire phonebook
bt_phonebook_pull address="AA:BB:CC:DD:EE:FF" save_path="~/contacts.vcf"


# Or search for specific contact
bt_phonebook_search address="AA:BB:CC:DD:EE:FF" field="name" value="John"

Using MCP Resources

Section titled “Using MCP Resources”

Resources provide live state without tool calls:

# In your MCP client, read these URIs:
bluetooth://adapters          # All adapters
bluetooth://paired            # Paired devices
bluetooth://connected         # Connected devices
bluetooth://device/AA:BB:...  # Specific device details

Tips

Section titled “Tips”

Next Steps

Section titled “Next Steps”