{
  "markdown": "> English version: [README.en.md](README.en.md)\n\n# 米桥（Mi Fitness Data Bridge）\n\n[![Glama score](https://glama.ai/mcp/servers/shkyyy18/mi_fitness_data_bridge/badges/score.svg)](https://glama.ai/mcp/servers/shkyyy18/mi_fitness_data_bridge)\n\n本地优先的数据桥接器，把**你自己的**小米运动健康数据导出到 SQLite、JSON、CSV、Python 以及兼容 MCP 的工具。\n\n*小米运动健康 App 很乐意给你看你的步数、睡眠和心率——却从不让你把这些数据带走。这个桥接器把你自己的数据放进你自己硬盘上的一个 SQLite 文件里。*\n\n<p align=\"center\"><img src=\"docs/assets/bridge-hero.png\" width=\"100%\" alt=\"米家设备通过米桥（Mi Fitness Data Bridge）连接各大 AI 模型\"></p>\n\n> **商标声明：小米、米家、Mi Fitness 均为小米公司商标。本项目为非官方社区项目，与小米公司无任何隶属或背书关系。**\n\n> 实验性的云端适配器可能因为小米改动私有接口而随时失效。请只在你有权访问的账号和数据上使用。\n\n## 实测验证\n\n2026-09-07 在 Windows（Python 3.14）上复核测试及合成导出流程。以下演示样本日期保留为 2026-07；测试只使用合成数据与 HTTP mock，不读取真实凭据，不请求真实小米端点。测试通过不代表真实账号的云端登录已恢复。\n\n测试套件：\n\n```text\n$ python -m pytest -q -p no:cacheprovider\n136 passed (2026-09-07 verification)\n```\n\n端到端合成演示（`examples/synthetic_demo.py` 先用合成记录填充本地 SQLite 缓存，再跑真实的 JSON/CSV 导出流水线）：\n\n```text\n$ python examples/synthetic_demo.py\nSeeded synthetic database: C:\\Users\\<you>\\AppData\\Local\\Temp\\mi-fitness-demo-53el7cfh\\mi_fitness.db\n  daily_activity: 2026-07-15 .. 2026-07-15 (1 day(s))\n  sleep: 2026-07-14 .. 2026-07-14 (1 day(s))\n  workouts: 2026-07-15 .. 2026-07-15 (1 day(s))\n  body_measurements: 2026-07-15 .. 2026-07-15 (1 day(s))\n\nExport completed\n  mi_fitness.json\n  daily_activity.csv\n  sleep.csv\n  workouts.csv\n  body_measurements.csv\n  heart_rate.csv\n  spo2.csv\n  stress.csv\n  abnormal_heart_beat.csv\n\nJSON envelope:\n  schema_version: 1.0\n  source: mi_fitness_data_bridge\n  records.daily_activity: 1 row(s)\n  records.sleep: 1 row(s)\n  records.workouts: 1 row(s)\n  records.body_measurements: 1 row(s)\n\nSample sleep row (synthetic):\n  start_at=2026-07-14T23:20:00 end_at=2026-07-15T07:05:00\n  duration_minutes=465 score=86\n  stages=[{\"stage\": \"deep\", \"minutes\": 82}, {\"stage\": \"light\", \"minutes\": 271}, {\"stage\": \"rem\", \"minutes\": 88}, {\"stage\": \"awake\", \"minutes\": 24}]\n```\n\n## 已合并 health-assistant 项目\n\n`health-assistant` 项目（本地优先的个人健康看板：Strava、睡眠、身体成分、饮食分析）已合并进本仓库，其原仓库已归档。吸收过来的资产位于 `docs/health-assistant/` 目录下：\n\n- `analytics.py` —— 零依赖的训练/恢复总结与建议引擎参考实现（7 天训练统计、急性/慢性负荷比、就绪度检查、每日训练建议）。\n- `coaching_methodology.md` —— 其背后可解释的骑行教练、身体成分与运动营养方法论。\n- `README.md` —— 完整的迁移说明，包括有意未移植的部分（FastAPI 看板、Strava OAuth/Webhook 管线、餐食照片分析）以及原因。\n\n## 这个项目做什么\n\n- 通过一个实验性的中国区云端适配器读取小米运动健康数据。\n- 把规范化后的记录存进本地 SQLite 数据库。\n- 导出不含凭据的便携式 JSON 或 CSV。\n- 暴露本地 MCP 查询工具，供个人自动化使用。\n- 为下游项目（比如个人减脂顾问）提供一份可复用的连接器实现。\n\n它刻意**不**提供医疗建议、减肥指导、托管式账号访问或多用户云服务。\n\n## 为什么做这个桥接器？\n\n| 之前 | 之后 |\n|---|---|\n| 你的健康历史只存在于小米运动健康 App 里，唯一的\"导出\"方式是截图。 | `mi-fitness-bridge sync` 把每日活动、睡眠、运动、身体测量、心率、血氧（SpO2）和压力拉进一个规范化的本地 SQLite 数据库。 |\n| 想回答\"我上个月睡得怎么样\"，得在 App 里一天天往回翻。 | `mi-fitness-bridge export --format csv --type sleep --start-date ... --end-date ...` 输出一个精确按该区间过滤、可直接用表格软件打开的 CSV。 |\n| 想让 AI 助手访问你的健康数据，就得把凭据交给某个托管服务。 | `mi-fitness-bridge serve` 基于你自己的数据库暴露本地 MCP 查询工具；passToken 留在操作系统钥匙串里，导出文件中永远不会包含它。 |\n\n## 支持的数据集\n\n- 每日活动：步数、距离、活动热量和活动分钟数。\n- 睡眠记录及睡眠阶段。\n- 运动记录。\n- 身体测量：体重及可用的身体成分字段。\n- 心率样本，包括可用时的静息心率。\n- 血氧（SpO2）、压力和异常心跳事件（取决于账号/设备是否提供）。\n\n实际可用性因设备、账号地区、固件和小米上游服务而异。\n\n## 安装\n\n```bash\ngit clone https://github.com/shkyyy18/mi_fitness_data_bridge.git mi_fitness_data_bridge\ncd mi_fitness_data_bridge\npython -m venv .venv\n```\n\nWindows PowerShell：\n\n```powershell\n.\\.venv\\Scripts\\Activate.ps1\npip install -e \".[dev]\"\n```\n\nWindows Git Bash：\n\n```bash\nsource .venv/Scripts/activate\npip install -e \".[dev]\"\n```\n\nmacOS/Linux：\n\n```bash\nsource .venv/bin/activate\npip install -e '.[dev]'\n```\n\n## 配置\n\n更安全的交互式配置路径可以避免把 passToken 直接写进 shell 历史：\n\n```bash\nmi-fitness-bridge setup\nmi-fitness-bridge doctor\n```\n\n在可用时，凭据通过本地钥匙串（keyring）存储。某些备用的 keyring 实现存储密钥的方式可能不够安全，使用前请先了解你操作系统的 keyring 行为。\n\n### 如何获取 user_id 和 passToken\n\n本桥接器使用的是小米账号级凭据（与米家 App 同一套登录态），以下两种方式任选其一：\n\n**方式一：浏览器手动复制**\n\n1. 在浏览器打开 [account.xiaomi.com](https://account.xiaomi.com) 并登录你的小米账号（与小米运动健康 App 同一个账号）。\n2. 打开开发者工具（F12）→「应用 / Application」→ Cookies → `https://account.xiaomi.com`。\n3. 复制 `userId` 和 `passToken` 两个 Cookie 的值，在 `mi-fitness-bridge setup` 提示时粘贴。\n\n**方式二：扫码登录工具**\n\n用开源的 [mijia-api](https://github.com/Do1e/mijia-api) 扫码登录一次：\n\n```bash\npip install mijiaAPI\npython -c \"from mijiaAPI import mijiaAPI; mijiaAPI().login()\"   # 终端出二维码，用米家 App 扫码\n```\n\n登录态默认保存在 `~/.config/mijia-api/auth.json`（Windows 为 `%USERPROFILE%\\.config\\mijia-api\\auth.json`），其中的 `userId` 和 `passToken` 即可直接用于本桥接器——小米账号级凭据跨服务通用，桥接器会用它换取小米运动健康（`sid=miothealth`）的会话。注意 `auth.json` 以明文保存凭据：把 `userId` 和 `passToken` 录入本桥接器（系统钥匙串）后，建议删除该文件。\n\n注意：\n\n- passToken 会过期；`doctor` 报认证失败时按上面步骤重新获取一次即可。\n- 浏览器法请在自己常用的网络环境下登录；频繁或异地操作可能触发小米账号风控（滑块/短信验证），如遇风控可改用扫码法。\n- Cookie 名称与登录流程基于 2026-08 的实测，可能因账号地区、设备或风控策略而异；小米也可能随时调整私有接口（见顶部实验性声明）。\n- 这两个值等同于你的账号登录态，请勿泄露，也请勿提交到 Git。\n\n## 同步\n\n```bash\nmi-fitness-bridge sync --start-date 2026-07-01 --end-date 2026-07-15\n```\n\n或者只同步某一个数据集：\n\n```bash\nmi-fitness-bridge sync --type sleep --start-date 2026-07-01 --end-date 2026-07-15\nmi-fitness-bridge sync --type body_measurements --start-date 2026-07-01 --end-date 2026-07-15\n```\n\n数据库默认落在平台用户数据目录（platformdirs 决定）。`sync`、`export`、`serve`、`doctor` 都支持用 `--db` 参数或 `MI_FITNESS_DB_PATH` 环境变量换位置，优先级：命令行 > 环境变量 > 默认位置。注意 platformdirs 在 Windows 上不响应 `LOCALAPPDATA` 环境变量，要自定义路径请用上述两种方式：\n\n```bash\nmi-fitness-bridge sync --db ./data/mi_fitness.db --start-date 2026-07-01 --end-date 2026-07-15\nexport MI_FITNESS_DB_PATH=./data/mi_fitness.db\n```\n\n已知限制：不带日期参数的增量同步以本地最后一条记录的时间为起点，上游对更早历史的修正或补录不会被自动拉到；需要时用更早的 `--start-date` 显式重跑该区间（会幂等覆盖，不会产生重复记录）。\n\n## 导出\n\n生成一个便携式 JSON 文件：\n\n```bash\nmi-fitness-bridge export --format json --output exports/mi_fitness.json\n```\n\n每个数据集各生成一个 CSV 文件：\n\n```bash\nmi-fitness-bridge export --format csv --output exports/csv\n```\n\n按数据集和日期过滤：\n\n```bash\nmi-fitness-bridge export --format json --type sleep \\\n  --start-date 2026-07-01 --end-date 2026-07-15 \\\n  --output exports/sleep.json\n```\n\n导出文件永远不会包含已保存的小米 passToken，但会包含明文 `user_id` 等标识列——导出文件属于敏感个人数据，请妥善保管。导出的健康记录默认已被 Git 忽略。\n\n导出格式说明（JSON 信封结构、CSV 布局、闭区间日期筛选规则）见 [Export format](docs/export-format.md)。\n\n## MCP 服务\n\n兼容命令仍然可用：\n\n```bash\nmi-fitness-bridge serve\n# legacy alias\nmi-fitness-mcp serve\n```\n\n可用的工具包括连接状态、同步、覆盖范围、每日摘要、身体测量、睡眠、运动、心率、血氧（SpO2）和压力查询，以及面向 agent 的 `workout_series` 运动时序工具——按 `max_points` 硬上限自动降采样（固定时间桶均值，SQLite 内聚合），并在响应中如实标注 `downsampled`、`source_points`、`returned_points`、`method`，同时给出全精度统计（avg/min/max/分位数）与心率区间时间。`query_workouts`、`get_daily_summary` 等列表/汇总工具附带 `data_quality`（覆盖天数、缺失指标、最后同步时间）。\n\n`query_sleep` 保留按入睡日期查询的原始缓存会话，并额外返回按本地醒来日期选择的主睡眠汇总和 `data_quality`。同一醒来日有手机、手环等并行记录时，汇总视图只选择最长的有效非午睡会话；`include_naps` 只过滤原始会话列表，质量信息仍会报告该窗口的午睡数量。缺失日期会明确列出，绝不按 0 小时睡眠参与均值；睡眠评分只使用上游实际提供的值，不在本机推算。\n\n客户端接入示例（Claude Code / Codex 等 MCP 客户端的配置 JSON）：\n\n```json\n{\n  \"mcpServers\": {\n    \"mi-bridge\": {\n      \"command\": \"mi-fitness-bridge\",\n      \"args\": [\"serve\"]\n    }\n  }\n}\n```\n\n注意：`serve` 是 stdio 服务，通过标准输入输出与客户端通信，不是 HTTP 服务。直接在终端运行它会看似\"卡住\"——那是在等待客户端的 MCP 消息，属正常现象；日常请交给 MCP 客户端按上面的配置启动。\n\n## 作为 Python 依赖使用\n\n规范化适配器在兼容模块名下仍然可用：\n\n```python\nfrom mi_fitness_mcp.adapters.mi_fitness_cloud import MiFitnessCloudAdapter\n```\n\n下游项目应当安装本包，而不是 vendor 或复制连接器源码。\n\n## 许可证\n\n许可证沿革：2026-08-03 之前发布的版本采用 MIT 许可（上游 `kubulashvili/mi-fitness-mcp` 与 `binglua/mi-fitness-mcp-cn` 的 MIT 归属保留在 `LICENSE` 顶部的 NOTICE 区块）；当前版本的新增代码采用 AGPL-3.0-only。详见 `LICENSE` 与 `THIRD_PARTY_NOTICES.md`。\n\n## 隐私与安全\n\n- 妥善保管 passToken、本地数据库、导出文件和日志，不要外泄。\n- 导出文件不含 passToken，但含明文 `user_id` 等标识列，同样属于敏感个人数据。\n- `query_*` 工具返回的健康数据会经由 MCP 客户端进入其背后的云端大模型；本服务只应通过本机 stdio 接入本机客户端，不要配置给远程或托管 agent。\n- 不要把本桥接器当作公开的凭据代理来运行。\n- 不要提交真实健康数据或包含个人指标的截图。\n- 在 bug 报告和文档中一律使用合成数据。\n- 本软件仅用于个人数据访问和工程研究，不用于诊断或治疗。\n\n负责任披露方式见 `SECURITY.md`，出处溯源见 `THIRD_PARTY_NOTICES.md`。\n\n## 开发\n\n```bash\npip install -e '.[dev]'\npython -m pytest -q -p no:cacheprovider\npython -m ruff check src tests\n```\n\n## 发布\n\n版本历史见 `CHANGELOG.md`，发布及发布后检查项见 `docs/release-checklist.md`。\n\n## 相关项目\n\n- [garmin-mcp](https://github.com/davidmosiah/garmin-mcp) —— 本地优先的 Garmin 数据 MCP 服务。与本项目共享 `agent-safe-series/v1` 数据契约（时间序列降采样字段语义逐字节对齐），同一个 AI agent 可以无缝消费两个服务的数据。\n\n## 支持这个项目\n\n如果这个工具帮到了你，在 [GitHub](https://github.com/shkyyy18/mi_fitness_data_bridge) 上帮我点个 star 吧。\n",
  "bytes": 8043,
  "sha": "e5b6158c5c721b9c66dbd47bd4fef6187144c0be127259131e1d1fe2a4cd55a9",
  "repo_slug": "shkyyy18/mi-fitness-data-bridge",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_shkyyy18_mi_fitness_data_bridg_b6a6aff7/readme"
}