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.

Related MCP server: API Tester MCP Server

✨ 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

Running the Server

Using 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 for Bluetooth devices:

   Could you scan for nearby Bluetooth devices?

🧪 Testing

This project follows a Test-Driven Development (TDD) approach with comprehensive test coverage:

🏗️ Architecture

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

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:

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.

🙏 Acknowledgements

• FastAPI for the API framework

• Bleak for cross-platform Bluetooth functionality

• Anthropic Claude for MCP integration support