---
title: Introduction
description: What is mcbluetooth and why use it?
---

**mcbluetooth** is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives LLMs full control over the Linux Bluetooth stack via BlueZ.

## What Can You Do?

Ask Claude (or any MCP-compatible LLM) to:

- **"Turn on Bluetooth and make my computer discoverable"**
- **"Scan for devices and pair with my Sony headphones"**
- **"Connect my headphones and set volume to 80%"**
- **"Read the battery level from my fitness tracker"**
- **"Send this PDF to my phone via Bluetooth"**
- **"Download my phone's contacts"**
- **"Start capturing Bluetooth traffic for debugging"**

## Why mcbluetooth?

### Natural Language Control

Instead of memorizing `bluetoothctl` commands or navigating GUI menus, just describe what you want:

```
"My headphones disconnected, reconnect them and set them as the default audio output"
```

### Complete BlueZ Coverage

mcbluetooth exposes the full power of BlueZ:

- **Adapters** — Power, discovery, pairing acceptance
- **Devices** — Scanning, pairing, connection management
- **Audio** — A2DP/HFP profiles, volume, routing
- **BLE/GATT** — Services, characteristics, notifications
- **OBEX** — File transfer, phonebook, messages
- **Monitoring** — HCI packet capture and analysis

### Smart Pairing

The built-in pairing agent handles all Bluetooth pairing methods:

| Method | Description | Agent Response |
|--------|-------------|----------------|
| Just Works | No user interaction | Auto-accept |
| Numeric Comparison | Confirm 6-digit code | Interactive or auto |
| Passkey Entry | Enter code from device | PIN prompt |
| Legacy PIN | 4-6 digit PIN | PIN prompt |

### MCP Resources

Live state queries without tool calls:

```
bluetooth://adapters     → All Bluetooth adapters
bluetooth://paired       → Paired devices
bluetooth://connected    → Connected devices
bluetooth://device/AA:BB:CC:DD:EE:FF → Specific device
```

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                     Claude / LLM                            │
├─────────────────────────────────────────────────────────────┤
│                    MCP Protocol (stdio)                     │
├─────────────────────────────────────────────────────────────┤
│                   mcbluetooth (FastMCP)                     │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐           │
│  │ Adapter │ │ Device  │ │  Audio  │ │  OBEX   │  ...      │
│  │  Tools  │ │  Tools  │ │  Tools  │ │  Tools  │           │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘           │
│       └──────────┬┴──────────┬┴───────────┘                │
│         ┌────────┴────────┐  │                              │
│         │  BlueZ D-Bus    │  │  PipeWire/Pulse              │
│         │   (dbus-fast)   │  │  (pulsectl-asyncio)          │
│         └────────┬────────┘  └──────────────────────────────┤
├──────────────────┼──────────────────────────────────────────┤
│                  │                                          │
│           BlueZ (bluetoothd)          obexd                 │
│                  │                                          │
│                Linux Kernel (Bluetooth subsystem)           │
└─────────────────────────────────────────────────────────────┘
```

## Requirements

| Requirement | Version | Notes |
|-------------|---------|-------|
| Linux | Any | BlueZ is Linux-only |
| Python | 3.11+ | Async/await, type hints |
| BlueZ | 5.x | Bluetooth daemon |
| PipeWire or PulseAudio | Any | For audio features |
| bluez-obex | Any | For OBEX features (optional) |

## Next Steps

1. [Install mcbluetooth](/getting-started/installation/)
2. [Try the quick start guide](/getting-started/quick-start/)
3. [Explore the tool reference](/reference/tools/)