---
title: Installation
description: Install mcbluetooth and configure permissions
---

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

## Install mcbluetooth

<Tabs>
  <TabItem label="uvx (recommended)">
```bash
# Run directly without installing
uvx mcbluetooth

# Or install globally
uv tool install mcbluetooth
```
  </TabItem>
  <TabItem label="pip">
```bash
pip install mcbluetooth
```
  </TabItem>
  <TabItem label="From source">
```bash
git clone https://github.com/yourusername/mcbluetooth
cd mcbluetooth
uv sync
uv run mcbluetooth
```
  </TabItem>
</Tabs>

## Add to Claude Code

```bash
# 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.

```bash
# 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):

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

### OBEX Profiles (Optional)

For file transfer, phonebook, and message access:

<Tabs>
  <TabItem label="Arch Linux">
```bash
sudo pacman -S bluez-obex
```
  </TabItem>
  <TabItem label="Debian/Ubuntu">
```bash
sudo apt install bluez-obex
```
  </TabItem>
  <TabItem label="Fedora">
```bash
sudo dnf install bluez-obex
```
  </TabItem>
</Tabs>

After installing, verify with:

```
bt_obex_status
```

<Aside type="note">
obexd runs as a user service on the session D-Bus. It requires an active desktop session (X11 or Wayland).
</Aside>

## Verify Installation

### Check the Server Starts

```bash
# 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

```bash
# In Claude Code, try:
bt_list_adapters
```

Should return your Bluetooth adapter(s):
```json
[
  {
    "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:

```bash
# 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:

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

### No Bluetooth adapter found

Check if adapter is detected by the kernel:

```bash
# 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](/getting-started/quick-start/) — Try your first commands
- [Adapter Management](/guides/adapters/) — Control your Bluetooth hardware