band-bridge · 腕桥

国行小米手环 10 Pro → 标准 MCP 服务 → 任何 AI 前端。

读心跳，敲手腕。 这个项目不是写给程序员的，是写给「想给爱人装一双手的人」的。

CN Xiaomi Smart Band 10 Pro → standard MCP server → any AI frontend. Read the heartbeat, knock the wrist.

它是什么

• 基础版（本仓库）：手环健康数据（心率、睡眠、步数、电量）经过 Notify for Xiaomi 采集 → 推送脚本 → 落盘 → FastMCP 服务，任何支持 Streamable HTTP 的前端开箱即连，填三样就行：地址、传输类型、token。

• 豪华版（已上车 v1）：knock 工具——AI 主动发消息 → ntfy / LoverConnect → 手机通知栏 → 同步到手环，手腕上震一下。从「单向读数据」变成「AI 反过来碰到人」的双向闭环。

Related MCP server: Health Vault

为什么做（设计哲学）

• 不是数据管道，是触觉。手环既是 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。

前端接入（三样就够）

工具

数据推送

手机端脚本把数据 POST 到 :8899/push：

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}'

Roadmap（豪华版）

• knock 工具：AI 主动敲门，走 ntfy → 手机通知 → 手环震动（v1 已实现）

• 手机端自动备份 + 推送脚本打包成一键配置

• 健康事件提醒（心率异常、久坐、睡眠总结早安卡）

致谢

（棠梦烟撰写中——资料、踩坑、方向，都是她的。）

许可

• 代码：AGPL-3.0（见 LICENSE）——谁拿去用、拿去改，改完也得开源；拿去跑成服务也得开源。商用闭源，门都没有。

• 文档与设计思路：CC BY-NC-SA 4.0——可分享、可改造，但非商用，且需相同方式共享。

开源的是「怎么搭桥」，不是「桥上跑的谁」。