Bluetooth MCP Server

Bluetooth MCP 服务

🔍 概述

本项目实现了一个 Model Context Protocol（MCP）服务，让 Claude 和其他 AI 助手能够扫描并与附近的 Bluetooth 设备交互。本项目采用测试驱动开发方法构建，为跨多个平台的 Bluetooth 操作提供了稳健且经过测试的接口。

✨ 功能

• 📡 多协议扫描：检测 BLE 和 Classic Bluetooth 设备
• 🔎 灵活筛选：按名称、类型或其他属性筛选设备
• 🔄 自动识别设备：识别并分类常见设备（如 Freebox、电视等）
• 📱 增强的设备信息：获取制造商信息、设备类型和详细特征
• 🖥️ 跨平台支持：适用于 Windows、macOS 和 Linux
• ⚡ 平台专属优化：增强 Windows 上的检测能力
• 🤖 MCP 集成：与 Claude 和兼容的 AI 助手无缝集成

📋 要求

• Python 3.7+
• Bluetooth 适配器（内置或外置）
• 管理员/sudo 权限（部分 Bluetooth 操作需要）
• 互联网连接（用于安装软件包）

🚀 快速开始

安装

# 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

运行服务

# Start the Bluetooth API server
python run.py

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

与 Claude 配合使用

1. 使用 ngrok 将服务公开到互联网，或将其部署到服务器：

   ngrok http 8000
   

2. 配置 Claude 使用你的 MCP 服务：

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

3. 让 Claude 扫描 Bluetooth 设备：

   Could you scan for nearby Bluetooth devices?
   

🧪 测试

本项目遵循测试驱动开发（TDD）方法，并提供全面的测试覆盖：

# 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

🏗️ 架构

本项目采用模块化架构，各部分职责划分清晰：

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

如需了解详细的架构信息，请参阅 architecture.md。

🔧 故障排除

Bluetooth 问题

• “访问被拒绝”错误：以管理员/sudo 权限运行服务
• 未检测到适配器：确保已在系统设置中启用 Bluetooth
• 未找到设备：确保附近有可被发现的 Bluetooth 设备
• Windows 特定问题：检查 Bluetooth 服务是否正在运行（services.msc）

MCP 问题

• Claude 未检测到工具：确认 MCP 服务 URL 正确且可访问
• 执行错误：查看服务日志以获取详细错误信息

👥 贡献

欢迎贡献！请按以下步骤操作：

1. Fork 此代码库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 为你的功能编写测试
4. 实现你的功能
5. 确保所有测试通过
6. 提交你的更改（git commit -m 'Add amazing feature'）
7. 将分支推送到远程代码库（git push origin feature/amazing-feature）
8. 发起 Pull Request

📄 许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

🙏 致谢

• FastAPI 提供 API 框架
• Bleak 提供跨平台 Bluetooth 功能
• Anthropic Claude 提供 MCP 集成支持