0 Fork 0

mirror of https://github.com/This-weiyuqing/mi-fitness-health.git synced 2026-10-18 03:03:49 +08:00

Files

T

binglua 2dd32f1ee6 feat: REST API with API keys, QR login, and web dashboard (v0.2.0)

- REST API (FastAPI): all data endpoints, sync (foreground/background),
  coverage stats, interactive docs at /docs
- API key system: exchange Xiaomi credentials for mif_sk_* keys
  (multi-account contexts, last-used tracking, prefix revocation);
  static key via MI_FITNESS_API_KEY, admin endpoints via MI_FITNESS_ADMIN_KEY
- QR code login: reverse-engineered Xiaomi universal QR flow
  (sid=xiaomiio), auto-issues API key after scan confirmation
- Built-in web dashboard (Flask): visual console for all endpoints,
  key management, QR login; reverse proxy with server-side key relay
- Standalone testpage/ console (python app.py, no install needed)
- Fix: pin mcp<2 (SDK 2.x removed Server.list_tools, broke startup)
- CI: install [all,dev] extras; docs: full technical documentation
  and QR login implementation guide

2026-09-03 22:28:31 +08:00

6.4 KiB

Raw Blame History

Mi Fitness MCP CN

小米运动健康（Mi Fitness）数据的本地 MCP Server + REST API + 现代化可视化 Web 仪表盘。把你自己账号里的健康数据同步到本地 SQLite，供 AI 客户端（MCP）、其他程序（HTTP API）或直接在现代化 Web 控制台查询分析。

基于 kubulashvili/mi-fitness-mcp 修改并深度重构，新增：

🇨🇳 中国区云端适配（--region cn）
💤 全量健康指标：睡眠分期（深睡/浅睡/REM/小睡）、运动记录、静息心率、血氧（SpO₂）、压力、异常心跳
🌐 REST API 服务（FastAPI）：全部数据端点 + 多维指标聚合，供任意程序调用
🖥️ 现代化 Web 仪表盘与控制台（Python Flask）：高质感深浅主题、图表走势、实时响应检视、cURL 一键生成
🔑 API Key 体系：用小米凭据换取 mif_sk_* Key（类大模型平台风格），支持多账号、可吊销
📱 扫码登录：逆向小米官方扫码流程，手机 App 扫码即可授权，告别浏览器 F12 抓 Cookie

⚠️ 非小米官方项目。全部云端接口为逆向所得，仅用于读取和分析你自己的健康数据，请遵守小米用户协议。接口随时可能因小米改版失效。

支持的数据

类型	内容	CLI `--type`	API 端点
每日活动	步数、距离、活动卡路里	`daily_activity`	`/api/summary`
心率	逐分钟采样 + 静息心率	`heart_rate`	`/api/heart-rate`
睡眠	时长、入睡/清醒、分段（深睡/浅睡/REM）	`sleep`	`/api/sleep`
运动	类型、时长、距离、卡路里、心率、配速	`workouts`	`/api/workouts`
身体成分	体重、BMI、体脂、肌肉量等（需体脂秤）	`body_measurements`	`/api/body-measurements`
血氧	SpO₂ 采样	`spo2`	`/api/spo2`
压力	压力分数 + 等级	`stress`	`/api/stress`
异常心跳	事件起止与时长	`abnormal_heart_beat`	`/api/abnormal-heart-beat`

快速开始

安装

git clone https://github.com/<your-name>/mi-fitness-mcp-cn.git
cd mi-fitness-mcp-cn
python -m venv .venv
source .venv/bin/activate      # Windows: .venv\Scripts\activate
pip install -e '.[all,dev]'    # 安装所有依赖（含 FastAPI 与 Flask Web UI）

要求 Python ≥ 3.11。

获取凭据与可视化控制台

方式 A：通过 Web 仪表盘扫码登录（最简单，推荐）

# 1. 启动后端 API 服务 (端口 8321)
mi-fitness-mcp api

# 2. 另开终端启动 Web 仪表盘 (端口 8322)
mi-fitness-mcp web

# 3. 浏览器打开 http://127.0.0.1:8322/ 点击「扫码登录」
# 用小米账号 / 米家 App 扫码确认，自动换取并注入 API Key！

方式 B：手动配置凭据

浏览器登录 account.xiaomi.com，从 Cookie 获取 userId 与 passToken：

mi-fitness-mcp setup --mode mi_fitness_cloud --user-id "<userId>" --pass-token "<passToken>" --region cn
mi-fitness-mcp doctor        # 验证连通性

数据同步

mi-fitness-mcp sync --start-date 2026-01-01 --end-date 2026-06-30   # 全量数据同步
mi-fitness-mcp sync --type sleep --start-date 2026-06-01 --end-date 2026-06-30 # 按类型同步

作为 MCP Server 接入 AI 客户端

在 Claude Desktop 或其它 MCP 客户端中配置：

{
  "mcpServers": {
    "mi-fitness": {
      "command": "mi-fitness-mcp",
      "args": ["serve"]
    }
  }
}

支持的 MCP 工具列表：

get_connection_status, sync_data, get_sync_status, get_profile, get_daily_summary
query_metric_series, query_heart_rate, query_body_measurements, query_sleep, query_workouts
query_spo2, query_stress, query_abnormal_heart_beat, get_data_coverage

REST API 与鉴权

启动 API 服务：

mi-fitness-mcp api [--host 127.0.0.1] [--port 8321]

交互式 Swagger 文档：http://127.0.0.1:8321/docs
鉴权机制：支持静态环境变量 MI_FITNESS_API_KEY、管理密钥 MI_FITNESS_ADMIN_KEY 以及通过 /api/auth/keys 动态发放的 mif_sk_* 用户级 Key。
扫码登录实现细节见 docs/QR_LOGIN.md，完整架构与协议文档见 docs/PROJECT_DOCUMENTATION.md。

# 携带 API Key 查询健康数据示例
curl "http://127.0.0.1:8321/api/summary?start_date=2026-08-01&end_date=2026-08-31" \
  -H "X-API-Key: mif_sk_..."

项目结构

src/mi_fitness_mcp/
├── main.py               # CLI 统一入口: serve / setup / doctor / sync / api / web
├── server.py             # MCP Server（14 个工具 + 异步同步引擎）
├── api.py                # REST API 服务（FastAPI: 数据端点 + Key 体系 + 扫码登录）
├── web.py                # 可视化仪表盘反向代理服务（Flask）
├── web_assets/           # 现代化前端界面（HTML / CSS / JS）
├── adapters/             # 小米云协议：登录、RC4加解密、签名、分页、解析
├── services/             # 同步引擎（分块/增量）与查询聚合
├── storage/              # SQLite 数据库引擎（8 张数据表 + sync_state）
├── models/               # Pydantic 数据模型
├── config.py             # 系统配置管理（platformdirs + JSON）
└── auth/                 # keyring 安全凭据存储
testpage/                 # 可选：独立运行的 Web 测试控制台（免安装，直接 python app.py）
docs/                     # 架构文档与扫码登录逆向原理解析
tests/                    # 单元测试与端到端测试套件

本地开发与测试

# 安装开发与测试依赖
pip install -e '.[all,dev]'

# 代码规范检查
ruff check src tests

# 运行完整测试套件
pytest -v

安全说明

passToken 等同小米账号登录态，切勿提交或泄露；若泄露，请在小米账号安全中心退出设备并重新登录。
本地数据库与敏感配置文件已在 .gitignore 中默认排除。
服务默认仅绑定 127.0.0.1 本地回环地址。如需向局域网或公网开放，请务必设置 MI_FITNESS_API_KEY 与 MI_FITNESS_ADMIN_KEY。

免责声明

本项目与小米公司无关。接口为社区逆向成果，不保证持续可用。请仅用于读取和分析您自己的个人健康数据。

License

MIT

6.4 KiB Raw Blame History Unescape Escape