Mi Fitness Data Bridge

English: README.en.md

Xiaomi デバイスデータエクスポートスキル（Mi Fitness Data Bridge）

Xiaomi Health（Mi Fitness）のデータを自分のパソコンに保存し、CSV、JSON、または SQLite にエクスポートできます。 個人用バックアップ、表計算ソフトでの整理、自作の分析プログラムに適しています。Python インターフェースと、ローカルの stdio MCP クエリツールも提供します。実際に取得できるデータの種類は、デバイス、アカウントの地域、上流サービスによって異なります。

非公式の実験的プロジェクトです。 本プロジェクトは Xiaomi との提携、承認、サポート関係にありません。Xiaomi、Mi Home、Mi Fitness は Xiaomi Corporation の商標です。アダプターは非公開の上流インターフェースに依存しているため、Xiaomi のサービス、アカウントの地域、デバイス、ファームウェア、認証方法の変更により、ログイン、接続、または一部のデータ種別がいつでも利用できなくなる可能性があります。アクセス権のあるアカウントとデータに限って使用してください。

▶ ログインせずに、合成データのエクスポートデモを見る · 互換性と利用開始時の制約 · English

結果を確認してからアカウントに接続

• エクスポート結果を見るだけですか？ 上記の静的デモを開き、ブラウザーでアクティビティ、睡眠、運動、身体測定のサンプルを切り替えて、合成 CSV / JSON をダウンロードできます。インストール、アカウント、トークンは不要です。
• ローカルの処理手順を確認しますか？ 以下のインストール手順を完了してから、python examples/synthetic_demo.py を実行してください。setup は不要で、Xiaomi への接続も行いません。
• 自分のデータを同期しますか？ まず互換性と認証情報の前提条件をお読みください。現在、ワンクリックでアカウント認証を行う手順はなく、すべてのデバイスや地域で利用できる保証もありません。

デモでは合成レコードのみを使用しており、実際のクラウド同期やデバイスの互換性を示すものではありません。静的デモページは認証情報や健康記録を受け取りません。実際のエクスポートには平文の user_id が含まれる場合があります。また、ローカル MCP だからといって AI ワークフロー全体がオフラインになるわけではありません。クライアントとモデルがデータをどのように扱うかは、別途ご確認ください。

スクリーンショットと本文中の例はすべて合成データです。認証情報、アカウント識別子、実際の健康データのエクスポートは含まれていません。

機能一覧

機能	説明
ローカルキャッシュ	同期して正規化したレコードを、ローカルの SQLite データベースに保存します。
ポータブルなエクスポート	JSON または CSV ファイルにエクスポートし、バックアップ、自作の分析ツールへの受け渡し、LLM へのインポートに利用できます。保存済みの passToken はエクスポートされません。
ローカル MCP サービス	標準入出力（stdio）を通じて、個人の自動化やローカル AI ワークフロー向けのクエリツールを提供します。
Python 統合	mi_fitness_mcp 名前空間を維持し、既存の下流利用者との互換性を確保します。

クラウドのデフォルトの地域は cn ですが、設定時に別の地域を指定することもできます。実際に利用できるレコードは、アカウントの地域、デバイス、ファームウェア、Xiaomi の上流サービスによって異なります。あるデータ種別の同期に成功してもレコード数が 0 件の場合は、指定した範囲にその種別のデータがないだけかもしれません。

対応データ

• 日常のアクティビティ：歩数、距離、アクティビティカロリー、アクティビティ時間、および関連フィールド。
• 睡眠：睡眠セッションと睡眠ステージ。
• 運動記録。
• 身体測定：体重、およびアカウントやデバイスから提供される体組成フィールド。
• 心拍数サンプル：利用可能な場合は安静時心拍数を含みます。
• 利用可能な場合は 血中酸素飽和度（SpO₂）、ストレス、異常心拍イベント。

日常のアクティビティの歩数は、ローカルの「分単位スライス」で集計します。スマートフォン、バンド、またはウォッチが同じ1分間に重複する記録を報告した場合、複数のデバイスによる二重計測を避けるため、合計せずに単一の記録のうち大きい値を保持します。このルールは非公開の上流データとの互換性を保つための最善の対応ですが、最終的な値は 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 の入力は非表示になるため、シェルの履歴に残りません：

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

設定では Mi Fitness の user_id、passToken、地域（デフォルトは cn）を尋ねられます。認証情報は利用可能な場合、ローカルのオペレーティングシステムのキーリングに保存されます。使用前に、現在のキーリングバックエンドのセキュリティ特性をご確認ください。passToken をコマンドライン、スクリプト、Issue、ログ、スクリーンショットに貼り付けないでください。setup は --user-id または --pass-token のコマンドライン引数を受け付けません。

doctor はローカルの設定、認証情報、データベースを確認します。認証情報が設定されている場合は、クラウドへの接続も確認します。クラウドの確認は、ネットワークや上流サービスの変更により失敗する場合がありますが、既存のローカルデータとエクスポート操作は引き続きオフラインで使用できます。

sync、export、serve、doctor は --db に対応しているほか、MI_FITNESS_DB_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 の選択肢：daily_activity、heart_rate、body_measurements、sleep、workouts、spo2、stress、abnormal_heart_beat。CLI はデータ種別ごとに、新規追加、更新、一部完了、失敗の状況を報告します。明示的な日付範囲を指定して同期を繰り返しても冪等で、既存のレコードは複製されません。Xiaomi が後から過去の日付のデータを修正した場合は、明示的に過去の --start-date を指定して、その範囲を再実行してください。

睡眠スコアが空になる（Issue #14）

睡眠の同期では、元のレコードに有効なスコアがある場合はそれを優先して保持します。メインの睡眠にスコアがない場合は、本人のアカウントの日次集計睡眠レポートから取得を試みます。ローカルの起床日、ソース、利用可能な睡眠区間の開始・終了時刻で照合し、明確に識別できたメインの睡眠にのみスコアを付与します。昼寝や別のデバイスに日次スコアをコピーしたり、スコアを独自に推定したりはしません。

• sleep_score_source は、sleep_record（元のレコード）または daily_report（日次レポート）を示します。古いキャッシュでソースが不明な場合は null です。日次レポートのスコアは、各睡眠区間に対して個別に算出されたスコアではありません。
• 引き続き非公式の実験的な互換対応です。 今回の検証は合成データと HTTP モックのみを対象としており、特定のデバイスや地域で動作確認済みであることを示すものではありません。KNOWN_REGIONS はルーティング候補であり、睡眠スコアの対応地域一覧ではありません。
• 集計インターフェースを利用できない場合、スコアがない場合、または照合が曖昧な場合は、通知を表示して基本の睡眠レコードを保持します。利用可能な過去のスコアがない場合は、引き続き null です。上流のデフォルト値であるスコア 0 は利用不可として扱い、0 点とは見なしません。同じ開始・終了時刻と昼寝フラグを持つ古いレコードには、最後に確認されたスコアが保持されるため、それが今回の同期で得られた最新結果とは限りません。
• この修正を含むコードに更新した後は、まず再同期し、その後エクスポートして、既存の MCP プロセスを再起動してください。export のみを再実行しても、新しいデータは取得されません。データベースの削除は不要です。初期化時にソース列が自動的に追加されます。

mi-fitness-bridge sync --type sleep --start-date 2026-09-13 --end-date 2026-09-21
mi-fitness-bridge export --format json --type sleep --start-date 2026-09-13 --end-date 2026-09-21 --output exports/sleep.json

上記は日付範囲の例です。日付をまたぐ睡眠の場合は、範囲を前後1日ずつ広げることができます。集計クエリではローカルの起床日を使用しますが、エクスポートでは従来どおり start_at で絞り込みます。詳しくはエクスポート形式をご覧ください。それでも空の場合は、デバイスのモデル、アカウントの地域、インストールしたバージョン、App にスコアが表示されるか、同期の状態のみをお知らせください。認証情報、実際の健康データ、データベース、ログはアップロードしないでください。

ローカルデータをエクスポート

JSON ファイルを1つエクスポートします：

mi-fitness-bridge export --format json --output exports/mi_fitness.json

CSV（データセットごとに1ファイル）をエクスポートします：

mi-fitness-bridge export --format csv --output exports/csv

データセットと日付で絞り込みます：

mi-fitness-bridge export --format json --type sleep \
  --start-date 2026-07-01 --end-date 2026-07-15 \
  --output exports/sleep.json

日付は YYYY-MM-DD 形式で指定し、開始日は終了日以前である必要があります。JSON は UTF-8 を使用し、CSV は BOM 付きの utf-8-sig を使用するため、Excel で日本語を正しく開けます。エクスポートした健康記録は機微な個人データであり、平文の user_id が含まれる場合があります。デフォルトの .gitignore はデータベース、エクスポートディレクトリ、一般的なログを無視しますが、それらの保存、共有、バックアップは適切に行ってください。

JSON エンベロープ、CSV レイアウト、境界を含む日付絞り込みルールについては、エクスポート形式の説明（英語）をご覧ください。

MCP 服务

启动本地 stdio MCP 服务：

mi-fitness-bridge serve
# 兼容别名
mi-fitness-mcp serve

可用工具包括：get_connection_status、sync_data、get_sync_status、cancel_sync、query_sync_history、get_profile、query_daily_activity、query_metric_series、get_data_coverage、query_body_measurements、query_sleep、query_workouts、query_workout_series、workout_detail_series、query_heart_rate、query_spo2、query_stress 和 query_abnormal_heart_beat。旧名称 get_daily_summary 和 workout_series 仍可作为兼容调用，但不会出现在工具目录中。

记录列表查询支持 limit/offset 分页，响应中的 data.pagination.next_offset 为下一页位置；翻页时保持筛选条件不变，且不要执行同步。单次运动曲线使用 query_workout_series 的 max_points 控制点数，不使用列表分页。后台 MCP 同步可用 cancel_sync 停止，已写入的记录不会回滚。任务状态保存在本地 SQLite 中，重启后可用 get_sync_status 或 query_sync_history 查询；保留最近 500 个终态 MCP 任务及活动任务，不包含 CLI 同步。重启时未完成任务会标记为 interrupted，不会自动续跑。同一数据库同时只允许一个 MCP 服务进程使用。

服务通过标准输入/输出通信，应由本机 MCP 客户端启动和管理；直接在终端运行时看似“卡住”是因为它正在等待 MCP 消息。它不会在启动时连接小米，只有状态检查或同步操作才按需建立云端连接。不要将它暴露为公网服务或凭证代理。

客户端配置示例：

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

完成 workout_detail 同步后，可通过 workout_detail_series 查询设备提供的秒级心率、步频、配速及速度曲线，并通过 workout_gps 导出 GPS 轨迹。默认全量同步会回填缓存中缺少明细的运动，force_full_sync 可重新抓取已覆盖的运动。非官方 FDS 协议仍受设备及固件版本限制，详见 运动明细可行性说明。

作为 Python 依赖使用

兼容包名保持为 mi_fitness_mcp：

from mi_fitness_mcp.adapters.mi_fitness_cloud import MiFitnessCloudAdapter

不要硬编码真实凭证，也不要将它们提交到源代码管理。下游项目应安装本包，而不要供应或复制其源码。

合成端到端演示

仓库包含完全不访问网络或真实账户的演示：

python examples/synthetic_demo.py

它会创建临时 SQLite 数据库、写入合成记录，并运行真实的 JSON/CSV 导出流程。可用于验证本地导出路径，或准备不泄露隐私的 Bug 报告。

开发

pip install -e '.[dev]'
python -m pytest -q -p no:cacheprovider
python -m ruff check src tests

Issue、测试、文档和截图中只可使用合成数据。安全问题请遵循 SECURITY.md；发布步骤请见 docs/release-checklist.md。

隐私、来源与许可

• 将 passToken、SQLite 数据库、导出文件和日志保密。
• 不要提交真实健康数据，或包含个人指标的截图。
• query_* MCP 工具返回的健康数据会流入你使用的 MCP 客户端；仅限本机 stdio 客户端使用，切勿接入远程或托管代理。
• 本软件仅用于个人数据访问和工程研究，不用于诊断或治疗。
• 上游来源和 MIT 归属见 THIRD_PARTY_NOTICES.md。

当前版本采用 AGPL-3.0-only 许可证；2026-08-03 之前发布的版本为 MIT。详见 LICENSE。

帮助项目成长

如果这个工具对你有用，欢迎点一个 Star，帮助有相同需求的人发现它。更有价值的是安全反馈兼容性、改进安装文档或提供合成复现。请勿上传凭证或真实健康数据。