蓝牙-MCP-服务器
项目介绍
蓝牙MCP服务器
<div align="center">
用于蓝牙设备检测的模型上下文协议服务器
</div>🔍 概述
该项目实现了一个模型上下文协议（MCP）服务器，使Claude和其他AI助手能够扫描并与其附近的蓝牙设备进行交互。采用测试驱动开发方法构建，它提供了一个强大且经过测试的跨平台蓝牙操作接口。
✨ 特性
- 📡 多协议扫描：检测BLE和经典蓝牙设备
- 🔎 灵活过滤：按名称、类型或其他属性过滤设备
- 🔄 自动设备识别：识别并分类常见设备（如Freebox、电视等）
- 📱 增强设备信息：获取制造商信息、设备类型和详细特征
- 🖥️ 跨平台支持：适用于Windows、macOS和Linux
- ⚡ 平台特定优化：在Windows上增强了检测能力
- 🤖 MCP集成：与Claude和兼容的AI助手无缝集成
📋 要求
- Python 3.7+
- 蓝牙适配器（内置或外置）
- 管理员/超级用户权限（某些蓝牙操作需要）
- 互联网连接（用于安装包）
🚀 快速开始
安装
# 克隆仓库
git clone https://github.com/yourusername/bluetooth-mcp-server.git
cd bluetooth-mcp-server
# 创建并激活虚拟环境
python -m venv venv
# 在Windows上
venv\Scripts\activate
# 在macOS/Linux上
source venv/bin/activate
# 安装依赖
pip install -r requirements.txt
# 配置环境变量
cp .env.example .env
# 根据需要编辑.env文件
运行服务器
# 启动蓝牙API服务器
python run.py
# 在另一个终端中启动MCP服务器
python bluetooth_mcp_server.py
与Claude一起使用
-
使用ngrok将您的服务器暴露到互联网，或将它部署到服务器：
ngrok http 8000 -
配置Claude以使用您的MCP服务器：
npx @anthropic-ai/sdk install-model-context-protocol <YOUR_SERVER_URL> -
让Claude扫描附近的蓝牙设备：
你能扫描一下附近的蓝牙设备吗？
🧪 测试
本项目遵循测试驱动开发（TDD）方法，并具有全面的测试覆盖率：
# 运行所有测试
pytest
# 运行特定测试类别
pytest tests/api/ # API测试
pytest tests/models/ # 数据模型测试
pytest tests/services/ # 服务逻辑测试
pytest tests/utils/ # 工具函数测试
🏗️ 架构
项目遵循模块化架构，职责分明：
bluetooth-mcp-server/
├── app/ # 主应用包
│ ├── api/ # FastAPI端点
│ ├── core/ # 核心配置
│ ├── data/ # 静态数据（蓝牙标识符等）
│ ├── models/ # 数据模型
│ ├── services/ # 业务逻辑
│ └── utils/ # 工具函数
├── mcp_sdk/ # MCP集成SDK
└── tests/ # 测试套件
有关详细的架构信息，请参阅architecture.md。
🔧 故障排除
蓝牙问题
- “访问被拒绝”错误：使用管理员/超级用户权限运行服务器
- 适配器未检测到：确保系统设置中的蓝牙已启用
- 未发现任何设备：确保附近有可发现的蓝牙设备
- Windows特定问题：检查蓝牙服务是否处于活动状态（
services.msc）
MCP问题
- 工具未被Claude检测到：验证您的MCP服务器URL是否正确且可访问
- 执行错误：查看服务器日志以获取详细的错误信息
👥 贡献
欢迎贡献！请遵循以下步骤：
- 分叉仓库
- 创建功能分支（
git checkout -b feature/amazing-feature） - 为您的功能编写测试
- 实现您的功能
- 确保所有测试通过
- 提交更改（
git commit -m '添加了惊人的功能'） - 推送到分支（
git push origin feature/amazing-feature） - 打开拉取请求
📄 许可证
本项目根据MIT许可证发布 - 详情见LICENSE文件。
🙏 致谢
- FastAPI 用于API框架
- Bleak 用于跨平台蓝牙功能
- Anthropic Claude 用于MCP集成支持