BL
Media

Bluetooth MCP Server for Discovery, Pairing, Audio Control

Control Bluetooth devices with an MCP server via natural language for discovery, pairing, and audio control.

View on GitHub
Quick Install
npx -y @Hypijump31/bluetooth-mcp-server

Overview

This Bluetooth MCP (Model Context Protocol) Server provides a programmatic bridge between natural-language agents (LLMs) and Bluetooth-capable devices. It exposes a small set of HTTP endpoints that implement discovery, pairing, and audio control workflows so a model or application can request Bluetooth operations using plain text instructions. The server is useful for building voice assistants, robotics controllers, or desktop automations that need to find and manage Bluetooth peripherals without embedding low-level Bluetooth logic in the agent itself.

The server is designed to be run close to the Bluetooth adapter (for example on a Linux machine with BlueZ or on a Raspberry Pi). It can be integrated as an MCP tool in an LLM orchestration environment, or used directly via REST calls. Because Bluetooth operations require platform-specific permissions and adapters, this server centralizes the platform interactions and exposes a stable, model-friendly API.

Features

  • Discover nearby Bluetooth devices (scan, RSSI, device type)
  • Initiate and complete pairing/bonding flows
  • Control audio routing (connect/disconnect A2DP/HFP devices, mute/unmute)
  • Natural-language-friendly endpoints for MCP-style usage
  • Simple REST API suitable for LLM tool wrappers or direct usage
  • Configurable adapter and authentication options
  • Optional Docker support for easy deployment

Installation / Configuration

Prerequisites:

  • A machine with a Bluetooth adapter (Linux/BlueZ recommended)
  • Python 3.9+ and pip, or Docker

Clone the repository:

git clone https://github.com/Hypijump31/bluetooth-mcp-server.git
cd bluetooth-mcp-server

Install with pip:

python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
python -m bluetooth_mcp_server.main

Run with Docker:

docker build -t bluetooth-mcp-server .
docker run --device /dev/ttyAMA0 --cap-add=NET_ADMIN -p 8080:8080 \
  -e MCP_PORT=8080 -e AUTH_TOKEN=yourtoken \
  bluetooth-mcp-server

Environment variables (common):

# HTTP port to listen on
MCP_PORT=8080

# Bluetooth adapter to use, e.g. "hci0"
BLUETOOTH_ADAPTER=hci0

# Simple bearer token for API calls
AUTH_TOKEN=changeme

# Optional: enable debug logs
LOG_LEVEL=debug

Permissions:

  • On Linux you may need to run under a user in the bluetooth group or use sudo for adapter control.
  • BlueZ daemon must be running (systemd service: bluetooth).

Available Resources

API endpoints (HTTP) — summary table:

EndpointMethodDescription
/discoverPOSTStart a scan, return discovered devices and metadata
/pairPOSTBegin and complete pairing with a specified device
/connectPOSTConnect to a paired device (audio or profile)
/disconnectPOSTDisconnect an active device
/audio/controlPOSTControl audio actions: set output, mute, unmute, volume
/statusGETRetrieve current adapter and device status

Example: start discovery (curl)

curl -X POST "http://localhost:8080/discover" \
  -H "Authorization: Bearer yourtoken" \
  -H "Content-Type: application/json" \
  -d '{"timeout": 8, "filter": {"name_contains": "Headset"}}'

Example: pair with device

curl -X POST "http://localhost:8080/pair" \
  -H "Authorization: Bearer yourtoken" \
  -H "Content-Type: application/json" \
  -d '{"address": "AA:BB:CC:DD:EE:FF", "pin": "0000"}'

MCP integration note: When used as a tool for an LLM, wrap the above endpoints in the tool definition so the model can call them as part of a conversation. The server returns structured JSON responses suitable for model consumption.

Use Cases

  • Smart home assistant: “Find nearby Bluetooth speakers and pair the living room speaker, then set it as the default audio output.” The model can call /discover, choose the correct device from results, call /pair, and then /audio/control to route audio.
  • Conference room setup: Automate connecting a presenter’s headset to the room audio system via a short natural-language command issued by a management UI.
  • Robotics: A robot can be instructed to “connect to the operator’s controller” where the server handles scanning and pairing while the robot focuses on higher-level tasks.
  • Testing automation: CI systems can run device discovery and exercise pairing flows to validate Bluetooth device firmware, using the API programmatically.

Security & Troubleshooting

  • Authentication: Use a strong AUTH_TOKEN or integrate with a reverse proxy and OAuth for production.
  • Adapter issues: Ensure the adapter name (BLUETOOTH_ADAPTER) matches the host system (hci0 is common). Verify with hciconfig or bluetoothctl show.
  • Permissions: If pairing fails, run the server with elevated privileges or set correct group permissions for Bluetooth device nodes.
  • Logs: Increase LOG_LEVEL to debug to capture interaction details when diagnosing pairing failures or profile connection errors.

Additional Resources

  • Repository: https://github.com/Hypijump31/bluetooth-mcp-server
  • System tools to know: bluetoothctl, hciconfig, BlueZ documentation
  • Recommended: Run the server on the same network segment and physical host as the Bluetooth adapter for reliable results.
Tags:media