Mi Fitness Data Bridge MCP server

English: README.en.md

小米设备数据导出skill（Mi Fitness Data Bridge）

把小米运动健康（Mi Fitness）数据保存到自己的电脑，导出为 CSV、JSON 或 SQLite。 适合个人备份、表格整理和自己的分析程序；也提供 Python 接口和本机 stdio MCP 查询工具。实际可获取的数据类型取决于设备、账户地区和上游服务。

非官方、实验性项目。 本项目与小米没有隶属、背书或支持关系；小米、米家（Mi Home）和 Mi Fitness 是小米公司的商标。适配器依赖非公开上游接口，小米的服务、账户地区、设备、固件或认证方式变化后，登录、连接或某些数据类型可能随时失效。仅可用于你有权访问的账户和数据。

▶ 不用登录，先看合成数据导出演示 · 兼容性与上手限制 · English

先试结果，再连接账户

• 只是想看导出效果？ 打开上面的静态演示，在浏览器中切换活动、睡眠、运动和身体测量样例，下载合成 CSV / JSON。无需安装、账号或 Token。
• 想验证本地流程？ 按下方安装步骤完成后，运行 python examples/synthetic_demo.py；无需 setup，不连接小米。
• 想同步自己的数据？ 先阅读兼容性和凭证前提。当前没有一键账号授权流程，也不能保证所有设备和地区可用。

演示只使用合成记录，不证明真实云端同步或设备兼容性。静态演示页不接收凭证或健康记录。真实导出可能含明文 user_id；本地 MCP 也不等于整个 AI 工作流离线，请另外确认客户端和模型如何处理数据。

截图和本文全部示例均为合成数据；不含凭证、账户标识符或真实健康导出数据。

功能一览

默认云端地区为 cn，也可在配置时指定其他地区。实际可用记录取决于账户地区、设备、固件及小米上游服务；某个数据类型同步成功但返回 0 条记录，可能只是指定范围内没有该类型数据。

支持的数据

• 日常活动：步数、距离、活动卡路里、活动分钟及相关字段。
• 睡眠：睡眠会话与阶段。
• 运动记录。
• 身体测量：体重，以及账户或设备提供的身体成分字段。
• 心率样本：包括可用时的静息心率。
• 可用时的 血氧（SpO₂）、压力和异常心跳事件。

日常活动的步数按本地“分钟切片”汇总：当手机、手环或手表对同一分钟上报重叠记录时，会保留较大的单条记录而不是相加，以避免双设备重复计步。该规则是对非公开上游数据的最佳兼容处理，最终数值仍可能与 App 的服务端修正结果不同。

项目边界

这是数据连接器和本地数据基础设施，明确不提供：

• 医疗诊断、治疗、健康教练或减重建议；
• 托管账户、共享凭证、公开 Token 代理或多用户云服务；
• Web 仪表盘、第三方健身 OAuth/Webhook 或餐食照片分析。

下游项目应安装本包或消费本地导出结果，而不是复制连接器源码。

安装

要求：Python 3.11 或更高版本。

git clone https://github.com/shkyyy18/mi_fitness_data_bridge.git
cd mi_fitness_data_bridge
python -m venv .venv

Windows PowerShell：

.\.venv\Scripts\Activate.ps1
pip install -e .

macOS / Linux：

source .venv/bin/activate
pip install -e .

安装开发依赖：

pip install -e '.[dev]'

主命令为 mi-fitness-bridge；旧命令 mi-fitness-mcp 仍保留为兼容别名。

配置与诊断

请使用交互式配置。passToken 提示会隐藏输入，避免它进入 shell 历史：

mi-fitness-bridge setup
mi-fitness-bridge doctor

配置过程会询问 Mi Fitness 的 userid、passToken 和地区（默认 cn）。凭证会在可用时保存到本机操作系统的密钥环；使用前请了解当前密钥环后端的安全特性。不要**在命令行、脚本、Issue、日志或截图中粘贴 passToken。setup 不接受 --user-id 或 --pass-token 命令行参数。

doctor 会检查本地配置、凭证和数据库；配置了凭证时还会检查云端连通性。云端检查可能因网络或上游服务变动失败，但已有本地数据和导出操作仍可离线使用。

sync、export、serve 和 doctor 支持 --db，也支持 MIFITNESSDB_PATH 环境变量指定数据库路径，优先级为：命令行参数 > 环境变量 > 配置/默认路径。

同步数据

同步日期范围内所有支持的数据类型：

mi-fitness-bridge sync --start-date 2026-07-01 --end-date 2026-07-15

只同步某一种数据：

mi-fitness-bridge sync --type sleep --start-date 2026-07-01 --end-date 2026-07-15
mi-fitness-bridge sync --type body_measurements --start-date 2026-07-01 --end-date 2026-07-15

--type 可选值：dailyactivity、heartrate、bodymeasurements、sleep、workouts、spo2、stress、abnormalheart_beat。CLI 会按数据类型报告新增、更新、部分完成和失败情况。指定明确日期范围的重复同步是幂等的，不会复制已有记录；若小米后来修正了较早日期，请用显式的较早 --start-date 重跑该范围。

睡眠分为空（Issue #14）

睡眠同步现在优先保留原始记录的有效评分；主睡眠缺少评分时，会尝试从本人账户的每日聚合睡眠报告补取。按本地醒来日期、来源及可用的睡眠段起止时间匹配，只给可明确识别的主睡眠补分；不把每日分数复制给小睡或其他设备，不自行估算。

• sleepscoresource 标明 sleeprecord（原始记录）或 dailyreport（每日报告）；旧缓存的未知来源为 null。每日报告分数不是对每段睡眠分别计算的评分。
• 仍属非官方、实验性兼容。 本次只经过合成数据和 HTTP mock 验证，不代表已验证某款设备或地区。KNOWN_REGIONS 只是路由候选，不是睡眠分兼容名单。
• 聚合接口不可用、无评分或匹配有歧义时，会提示但保留基础睡眠记录；没有可用历史评分时仍为 null。评分为 0 的上游默认值仍按不可用处理，不计为零分。相同起止时间与小睡标记的旧记录会保留最后已知评分，因此它不一定是本次同步的新结果。
• 更新包含此修复的代码后，先重新同步，再导出，并重启已有 MCP 进程。 只重跑 export 不会获取新数据。无需删除数据库，初始化时会自动添加来源列。

Shortened. The full README is on GitHub.