블루투스 MCP 서버

Bluetooth 장치 감지를 위한 모델 컨텍스트 프로토콜 서버

🔍 개요

이 프로젝트는 Claude를 비롯한 AI 비서들이 주변의 블루투스 기기를 스캔하고 상호작용할 수 있도록 하는 모델 컨텍스트 프로토콜(MCP) 서버를 구현합니다. 테스트 주도 개발(Test-Driven Development) 방식으로 구축되어 다양한 플랫폼에서 블루투스 작동을 위한 견고하고 검증된 인터페이스를 제공합니다.

Related MCP server: MCP Bridge Server

✨ 특징

• 📡 다중 프로토콜 스캐닝 : BLE 및 클래식 블루투스 장치 모두 감지

• 🔎 유연한 필터링 : 이름, 유형 또는 기타 속성으로 장치 필터링

• 🔄 자동 기기 인식 : 일반적인 기기(예: Freebox, TV 등)를 식별하고 분류합니다.

• 📱 향상된 기기 정보 : 제조업체 정보, 기기 유형 및 자세한 특성을 확인하세요.

• 🖥️ 크로스 플랫폼 지원 : Windows, macOS, Linux에서 작동합니다.

• ⚡ 플랫폼별 최적화 : Windows에서 향상된 감지 기능

• 🤖 MCP 통합 : Claude 및 호환 AI 어시스턴트와의 원활한 통합

📋 요구 사항

• 파이썬 3.7 이상

• Bluetooth 어댑터 (내장형 또는 외장형)

• 관리자/sudo 권한 (일부 Bluetooth 작업에 필요)

• 인터넷 연결 (패키지 설치용)

🚀 빠른 시작

설치

지엑스피1

서버 실행

# 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를 참조하세요.

🔧 문제 해결

블루투스 문제

• "액세스가 거부되었습니다" 오류 : 관리자/sudo 권한으로 서버를 실행하세요.

• 어댑터가 감지되지 않음 : 시스템 설정에서 Bluetooth가 활성화되어 있는지 확인하세요.

• 장치를 찾을 수 없습니다 . 근처에 검색 가능한 Bluetooth 장치가 있는지 확인하세요.

• Windows 관련 문제 : Bluetooth 서비스가 활성화되어 있는지 확인하세요( services.msc )

MCP 문제

• Claude가 도구를 감지하지 못했습니다 . MCP 서버 URL이 올바르고 액세스 가능한지 확인하세요.

• 실행 오류 : 자세한 오류 정보는 서버 로그를 확인하세요.

👥 기여하기

여러분의 참여를 환영합니다! 다음 단계를 따라주세요.

1. 저장소를 포크하세요

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. 풀 리퀘스트 열기

📄 라이센스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.

🙏 감사의 말

• API 프레임워크를 위한 FastAPI

• 크로스 플랫폼 블루투스 기능에 대한 암울함

• MCP 통합 지원을 위한 Anthropic Claude