Bluetooth MCP Server

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

git clone https://github.com/yourusername/bluetooth-mcp-server.git
cd bluetooth-mcp-server\n\n# Create and activate virtual environment
python -m venv venv\n\n# On Windows
venv\Scripts\activate\n\n# On macOS/Linux
source venv/bin/activate\n\n# Install dependencies
pip install -r requirements.txt\n\n# Configure environment variables
cp .env.example .env\n\n# Edit the .env file as needed
```\n\n### Running the Server
```bash\n\n# Start the Bluetooth API server
python run.py\n\n# In another terminal, start the MCP server
python bluetooth_mcp_server.py
```\n\n### Using with Claude
1. Expose your server to the internet using ngrok or deploy it to a server:
```bash
ngrok http 8000

2. Configure Claude to use your MCP server:

npx @anthropic-ai/sdk install-model-context-protocol

3. 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:

pytest\n\n# 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)\n\n### 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:

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

License

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