The Bluetooth MCP Server provides an MCP-compliant interface to discover and interact with nearby Bluetooth devices (both BLE and Classic). It exposes endpoints via a FastAPI-based API and integrates with Claude and other MCP-enabled assistants to enable device scanning, filtering, and retrieval of device information such as manufacturer data, device type, and characteristics. The server is designed to work across Windows, macOS, and Linux, and supports typical Bluetooth operations behind a simple MCP API surface. To get started, start the MCP server script alongside the Bluetooth API, then connect Claude or any MCP client to the server URL to begin scanning and querying devices. The tools include device discovery, filtering by name or attributes, and enriched device details suitable for AI-assisted device interaction.

In practice, you run the Python-based server (bluetooth_mcp_server.py) to expose MCP endpoints, and a separate API service (the Bluetooth API) that handles low-level Bluetooth operations. You can then use the MCP client tooling to instruct Claude to scan, filter, and describe nearby devices. The setup emphasizes test-driven development, verified with a suite of tests that cover API endpoints, data models, and service logic so you can trust the interface for automation and integration tasks.

Prerequisites:

• Python 3.7 or newer
• A Bluetooth adapter (built-in or external)
• Administrative privileges for certain Bluetooth operations
• Internet access for dependencies

Step-by-step installation:

1. Clone the repository git clone https://github.com/yourusername/bluetooth-mcp-server.git cd bluetooth-mcp-server

2. Create a virtual environment and activate it python -m venv venv

   On Windows

   venv\Scripts\activate

   On macOS/Linux

   source venv/bin/activate

3. Install dependencies pip install -r requirements.txt

4. Configure environment variables cp .env.example .env

   Edit the .env file as needed (e.g., adapter name, logs level)

5. Run the MCP server and API

   Start the Bluetooth MCP server (in one terminal)

   python bluetooth_mcp_server.py

   Start the Bluetooth API (in another terminal)

   python run.py

6. Verify operation

   • Ensure the server is reachable at the configured URL (e.g., http://localhost:8000)
   • Run available tests to confirm setup: pytest

Optional:

• If using Claude, expose the server publicly via ngrok or a reverse proxy and configure Claude to point to the MCP server URL.

Tips and common issues:

• Ensure your Bluetooth adapter is enabled and accessible; run with administrative privileges if you encounter 'Access denied' errors.
• If no devices are found, confirm that there are discoverable Bluetooth devices nearby and that the adapter supports the needed protocols (BLE and Classic).
• On Windows, verify Bluetooth services are active (services.msc) and that the correct driver is installed.
• For MCP integration, verify the MCP server URL is accessible to Claude or other clients and that proper authentication (if any) is configured.
• Review the test suite (pytest) to understand coverage areas: API endpoints, data models, and services.
• Check logs for detailed error information when troubleshooting execution or connectivity issues.