warehack.ing/mcbluetooth
2
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcbluetooth/docs-site/src/content/docs/getting-started/installation.md
Ryan Malloy 9d1c0f3e0f Add Astro/Starlight documentation site 
23-page docs site following diataxis principles with guides,
reference, and explanation sections covering all 61 MCP tools.
Bluetooth-themed design with Pagefind search.
2026-02-02 14:36:07 -07:00

3.5 KiB
Raw Blame History

title description
Installation Install mcbluetooth and configure permissions

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

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