Bluetooth MCP Server

🚀 Bluetooth MCP Server

A Model Context Protocol (MCP) server for Bluetooth device detection, enabling seamless interaction with AI assistants.

🚀 Quick Start

Installation

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

# Create and activate a virtual environment
python -m venv venv

# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment variables
cp .env.example .env
# Edit the .env file as needed

Run the Server

# Start the Bluetooth API server
python run.py

# In another terminal, start the MCP server
python bluetooth_mcp_server.py

Use with Claude

1. Expose your server to the internet using ngrok or deploy it to a server:

   ngrok http 8000
   

2. Configure Claude to use your MCP server:

   npx @anthropic-ai/sdk install-model-context-protocol <YOUR_SERVER_URL>
   

3. Ask Claude to scan nearby Bluetooth devices:

   Can you scan nearby Bluetooth devices?
   

✨ Features

• 📡 Multi-Protocol Scanning: Detect classic Bluetooth and Bluetooth Low Energy (BLE) devices.
• 🔎 Flexible Filtering: Filter devices by name, type, or other attributes.
• 🔄 Automatic Device Recognition: Identify and classify common devices (e.g., Freebox, TVs, etc.).
• 📱 Enhanced Device Information: Obtain manufacturer information, device types, and detailed features.
• 🖥️ Cross-Platform Support: Works on Windows, macOS, and Linux.
• ⚡ Platform-Specific Optimization: Enhanced detection capabilities on Windows.
• 🤖 MCP Integration: Seamlessly integrate with Claude and compatible AI assistants.

📋 Prerequisites

• Python 3.7+
• Bluetooth Adapter (built-in or external)
• Administrator/ sudo privileges (required for certain Bluetooth operations)
• Internet connection (for package installation)

🧪 Testing

This project uses Test-Driven Development (TDD) with comprehensive test coverage:

# Run all tests
pytest

# Run specific test categories
pytest tests/api/       # API tests
pytest tests/models/    # Data model tests
pytest tests/services/  # Service logic tests
pytest tests/utils/     # Utility tests

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• FastAPI for providing the API framework.
• Bleak for cross-platform Bluetooth functionality.
• Anthropic Claude for MCP integration support.