Bluetooth MCP Server

Model Context Protocol Server for Bluetooth Device Detection

🔍 Overview

This project implements a Model Context Protocol (MCP) server that enables Claude and other AI assistants to scan and interact with Bluetooth devices in your vicinity. Built with a Test-Driven Development approach, it provides a robust, tested interface for Bluetooth operations across multiple platforms.

✨ Features

📡 Multi-protocol scanning: Detect both BLE and Classic Bluetooth devices
🔎 Flexible filtering: Filter devices by name, type, or other attributes
🔄 Automatic device recognition: Identify and categorize common devices (like Freebox, TVs, etc.)
📱 Enhanced device information: Get manufacturer info, device type, and detailed characteristics
🖥️ Cross-platform support: Works on Windows, macOS, and Linux
⚡ Platform-specific optimizations: Enhanced detection capabilities on Windows
🤖 MCP Integration: Seamless integration with Claude and compatible AI assistants

📋 Requirements

Python 3.7+
Bluetooth adapter (built-in or external)
Admin/sudo privileges (required for some Bluetooth operations)
Internet connection (for package installation)

🚀 Quick Start

Installation

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

# Create and activate 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

Running the Server

# Start the Bluetooth API server
python run.py

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

Using with Claude

Expose your server to the internet using ngrok or deploy it to a server:
ngrok http 8000
Configure Claude to use your MCP server:
npx @anthropic-ai/sdk install-model-context-protocol <YOUR_SERVER_URL>
Ask Claude to scan for Bluetooth devices:
Could you scan for nearby Bluetooth devices?

🧪 Testing

This project follows a Test-Driven Development (TDD) approach 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 function tests

🏗️ Architecture

The project follows a modular architecture with clear separation of concerns:

bluetooth-mcp-server/
├── app/                # Main application package
│   ├── api/            # FastAPI endpoints
│   ├── core/           # Core configuration
│   ├── data/           # Static data (Bluetooth identifiers, etc.)
│   ├── models/         # Data models
│   ├── services/       # Business logic
│   └── utils/          # Utility functions
├── mcp_sdk/            # MCP integration SDK
└── tests/              # Test suites

For detailed architecture information, see architecture.md.

🔧 Troubleshooting

Bluetooth Issues

"Access denied" errors: Run the server with admin/sudo privileges
Adapter not detected: Ensure Bluetooth is enabled in your system settings
No devices found: Make sure there are discoverable Bluetooth devices nearby
Windows-specific issues: Check that Bluetooth services are active (services.msc)

MCP Issues

Tool not detected by Claude: Verify your MCP server URL is correct and accessible
Execution errors: Check the server logs for detailed error information

👥 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Write tests for your feature
Implement your feature
Ensure all tests pass
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

🙏 Acknowledgements

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

Integrations