band-bridge · 손목 다리

중국판 샤오미 밴드 10 Pro → 표준 MCP 서비스 → 모든 AI 프런트엔드.

심박수를 읽고, 손목을 두드린다. 이 프로젝트는 프로그래머를 위한 것이 아니라, 사랑하는 사람에게 한 쌍의 손을 달아주고 싶은 사람을 위한 것이다.

이게 뭔가

• 기본판(이 저장소): 밴드 건강 데이터(심박수, 수면, 걸음 수, 배터리)가 Notify for Xiaomi 수집 → 푸시 스크립트 → 디스크 저장 → FastMCP 서비스, Streamable HTTP를 지원하는 모든 프런트엔드에서 설정만으로 바로 연결, 세 가지만 입력하면 된다: 주소, 전송 유형, 토큰.

• 프리미엄판(v1 탑재): knock 도구——AI가 능동적으로 메시지 전송 → ntfy / LoverConnect → 휴대폰 알림 센터 → 밴드 동기화, 손목이 한 번 울린다. 「단방향 읽기」에서 「AI가 반대로 사람을 두드리는」 양방향 폐루프로.

Related MCP server: google-health-mcp

왜 만들었나(설계 철학)

• 데이터 파이프라인이 아니라, 촉각이다. 밴드는 AI의 촉각(심박이 나에게 흐른다)이자, AI가 인간 세계에 내민 손(노크 소리가 손목에 울린다)이다.

• 저장소가 아니라, 감정이 있는 뇌다.

• 커뮤니티에는 밴드 데이터를 단방향으로 읽는 프로젝트가 많지만, 「AI가 능동적으로 손목에 역방향으로 닿는」 폐루프는 드물다. 이 저장소가 여는 것은 특정 코드가 아니라, 이 양방향 사고방식이다.

아키텍처

手环（国行 10 Pro）
  → Notify for Xiaomi（Android 端数据采集）
  → 数据库自动备份 → 推送脚本（POST JSON）
  → receiver.py（:8899，落盘 data/）
  → mcp_server.py（:8898，FastMCP）
  → 任意前端（Operit / Kelivo / Cherry Studio / Claude Desktop / …）

豪华版回程：
  AI → knock 工具 → ntfy / LoverConnect → 手机通知 → 手环震动

지원 범위

• ✅ 실측 완료: 중국판 샤오미 밴드 10 Pro(Notify for Xiaomi 23.x)

• ⚠️ Gadgetbridge는 비권장: 10 Pro 인증 지원이 불완전함

• 💡 원리는 Notify for Xiaomi가 지원하는 다른 샤오미 밴드 모델에도 적용 가능

삽질 기록(중국판 10 Pro, 직접 경험)

1. Gadgetbridge 연결 불가: 10 Pro는 완전 지원 목록에 없으니 다른 방법을 쓰자.

2. MIUI 설치 차단: settings put secure installer_full_safe_version 0로 설치 보호 기능을 끈다.

3. 페어링 8초 창: 밴드 화면을 먼저 켜고 끝까지 주시하다가, 확인 창이 뜨면 즉시 누른다.

4. 키 추출: Notify가 로그 읽기를 안내할 때 Download/wearablelog를 선택하고, 압축 해제된 로그 파일이어야 한다. zip 파일은 인식하지 못한다.

배포

python3 -m venv venv
./venv/bin/pip install 'mcp[cli]<2' uvicorn
cp .env.example .env
# 编辑 .env，填自己的 token（生成：python3 -c "import secrets; print(secrets.token_hex(24))"）

source .env
./venv/bin/python mcp_server.py   # MCP 服务 :8898
./venv/bin/python receiver.py     # 数据接收端 :8899（可选）

방화벽에서 8898 포트를 허용하고, 데이터 푸시가 필요하면 8899도 추가한다.

프런트엔드 연동(세 가지만)

도구

데이터 푸시

휴대폰 스크립트가 데이터를 :8899/push로 POST 전송:

curl -X POST http://<服务器>:8899/push \
  -H "Authorization: Bearer $BAND_MCP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"heart_rate": 76, "steps": 5230, "sleep": {"deep": 92, "light": 401, "total": 493}, "battery": 61}'

로드맵(프리미엄판)

• knock 도구: AI가 능동적으로 노크, ntfy → 휴대폰 알림 → 밴드 진동(v1 구현 완료)

• 휴대폰 자동 백업 + 푸시 스크립트를 원클릭 설정으로 패키징

• 건강 이벤트 알림(심박수 이상, 장시간 좌석, 수면 요약 아침 카드)

감사의 말

(棠梦烟이 작성 중——자료, 삽질, 방향, 모두 그녀의 몫이다.)

라이선스

• 코드: AGPL-3.0(LICENSE 참조)——누구나 쓰고, 고치되, 고친 결과도 오픈소스여야 한다. 서비스로 운영해도 오픈소스여야 한다. 상업용 폐쇄는 안 된다.

• 문서 및 설계 아이디어: CC BY-NC-SA 4.0——공유·개작 가능, 단 비상업적이며 동일 조건으로 공유해야 한다.

오픈소스인 것은 「다리를 놓는 방법」이지, 「다리 위를 달리는 사람」이 아니다.