Installation

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

Install mcbluetooth

```bash # Run directly without installing uvx mcbluetooth

Or install globally

uv tool install mcbluetooth

  </TabItem>
  <TabItem label="pip">
```bash
pip install mcbluetooth

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

Add to Claude Code

# Using uvx
claude mcp add mcbluetooth -- uvx mcbluetooth

# From source
claude mcp add mcbluetooth -- uv run --directory /path/to/mcbluetooth mcbluetooth

Configure Permissions

BlueZ Access

mcbluetooth needs access to the BlueZ D-Bus interface. Most desktop Linux distributions allow this by default.

# Option 1: Add user to bluetooth group (requires re-login)
sudo usermod -aG bluetooth $USER

# Option 2: Verify polkit allows access (check for errors when running)
uvx mcbluetooth

HCI Packet Capture (Optional)

For bt_capture_* tools (btmon integration):

# Allow btmon without sudo
sudo setcap cap_net_raw+ep /usr/bin/btmon

OBEX Profiles (Optional)

For file transfer, phonebook, and message access:

```bash sudo pacman -S bluez-obex ``` ```bash sudo apt install bluez-obex ``` ```bash sudo dnf install bluez-obex ```

After installing, verify with:

bt_obex_status

obexd runs as a user service on the session D-Bus. It requires an active desktop session (X11 or Wayland).

Verify Installation

Check the Server Starts

# Should show startup banner and wait for MCP connections
uvx mcbluetooth

Expected output:

🔵 mcbluetooth v0.1.0
   BlueZ MCP Server - Bluetooth management for LLMs

Test with Claude Code

# In Claude Code, try:
bt_list_adapters

Should return your Bluetooth adapter(s):

[
  {
    "name": "hci0",
    "address": "AA:BB:CC:DD:EE:FF",
    "powered": true,
    "discoverable": false,
    "discovering": false
  }
]

Troubleshooting

”org.bluez was not provided”

BlueZ daemon isn’t running:

# Check status
systemctl status bluetooth

# Start if stopped
sudo systemctl start bluetooth
sudo systemctl enable bluetooth

“Permission denied” on D-Bus

Add user to bluetooth group:

sudo usermod -aG bluetooth $USER
# Log out and back in

No Bluetooth adapter found

Check if adapter is detected by the kernel:

# List USB devices
lsusb | grep -i bluetooth

# Check kernel module
lsmod | grep btusb

# Check dmesg
dmesg | grep -i bluetooth

obexd not found

Install the bluez-obex package for your distribution (see OBEX section above).

Tested Configurations

Distribution	BlueZ	Audio	Status
Arch Linux	5.85	PipeWire 1.4	✓ Full support
Ubuntu 22.04	5.64	PulseAudio	✓ Full support
Ubuntu 24.04	5.72	PipeWire	✓ Full support
Fedora 39	5.70	PipeWire	✓ Full support
Debian 12	5.66	PipeWire	✓ Full support

Next Steps

• Quick Start Guide — Try your first commands
• Adapter Management — Control your Bluetooth hardware