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
# 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
Metadata
Release files for iflow-mcp_hypijump31_bluetooth-mcp-server 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_hypijump31_bluetooth_mcp_server-0.1.0.tar.gz | 40.1 kB | Without provenance | Details for iflow_mcp_hypijump31_bluetooth_mcp_server-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_hypijump31_bluetooth_mcp_server-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_hypijump31_bluetooth_mcp_server-0.1.0-py3-none-any.whl |
Total release size: 86.0 kB
Release files / iflow_mcp_hypijump31_bluetooth_mcp_server-0.1.0.tar.gz
| Download URL | iflow_mcp_hypijump31_bluetooth_mcp_server-0.1.0.tar.gz |
|---|---|
| Size | 40.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
aa7b1c462622812c0449c7b29fd96534be2385e42d3312f00c21d2a544c53f63
|
|
BLAKE2b-256 checksum How to use checksums |
30bf0d110bb9fbecd101253afd6c75b0b96928108e4c08462bb9ae61f207fc96
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.17 {"installer":{"name":"uv","version":"0.9.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_hypijump31_bluetooth_mcp_server-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_hypijump31_bluetooth_mcp_server-0.1.0-py3-none-any.whl |
|---|---|
| Size | 45.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
63549973886a149e778e2b473d26e27c99c0d5cbd8171b95f418c176d2b9eb99
|
|
BLAKE2b-256 checksum How to use checksums |
692f4ea3a886b2f6450f576527d3ac7540c0d0914d2b6f876bfc513fc25ba714
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.17 {"installer":{"name":"uv","version":"0.9.17","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_hypijump31_bluetooth-mcp-server 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.