英語版: README.en.md

米橋（Mi Fitness Data Bridge）

ローカル優先のデータブリッジ。あなた自身の Xiaomi 運動健康データを SQLite、JSON、CSV、Python、および MCP 互換ツールにエクスポートします。

Xiaomi 運動健康アプリは歩数・睡眠・心拍数を喜んで表示してくれますが、それらのデータを持ち出すことは決して許可してくれません。このブリッジは、あなた自身のデータをあなた自身のハードディスク上の SQLite ファイルに格納します。

商標に関する声明：Xiaomi、米家、Mi Fitness はすべて Xiaomi 社の商標です。本プロジェクトは非公式のコミュニティプロジェクトであり、Xiaomi 社との提携・推奨関係は一切ありません。

実験的なクラウドアダプターは、Xiaomi がプライベート API を変更した場合にいつでも動作しなくなる可能性があります。アクセス権限のあるアカウントとデータでのみ使用してください。

実測検証

2026-07-20 に Windows（Python 3.14）上で main ブランチのコミットに基づいて録画されました。すべてのデータは合成データであり、認証情報やネットワークアクセスは一切含まれません。（テスト数は 2026-08-17 に再確認・更新済み。）

テストスイート：

$ python -m pytest -q -p no:cacheprovider
........................................................................ [ 96%]
...                                                                      [100%]
75 passed in 10.27s

エンドツーエンド合成デモ（examples/synthetic_demo.py はまず合成レコードでローカル SQLite キャッシュを埋め、その後実際の JSON/CSV エクスポートパイプラインを実行します）：

$ python examples/synthetic_demo.py
Seeded synthetic database: C:\Users\<you>\AppData\Local\Temp\mi-fitness-demo-53el7cfh\mi_fitness.db
  daily_activity: 2026-07-15 .. 2026-07-15 (1 day(s))
  sleep: 2026-07-14 .. 2026-07-14 (1 day(s))
  workouts: 2026-07-15 .. 2026-07-15 (1 day(s))
  body_measurements: 2026-07-15 .. 2026-07-15 (1 day(s))

Export completed
  mi_fitness.json
  daily_activity.csv
  sleep.csv
  workouts.csv
  body_measurements.csv
  heart_rate.csv
  spo2.csv
  stress.csv
  abnormal_heart_beat.csv

JSON envelope:
  schema_version: 1.0
  source: mi_fitness_data_bridge
  records.daily_activity: 1 row(s)
  records.sleep: 1 row(s)
  records.workouts: 1 row(s)
  records.body_measurements: 1 row(s)

Sample sleep row (synthetic):
  start_at=2026-07-14T23:20:00 end_at=2026-07-15T07:05:00
  duration_minutes=465 score=86
  stages=[{"stage": "deep", "minutes": 82}, {"stage": "light", "minutes": 271}, {"stage": "rem", "minutes": 88}, {"stage": "awake", "minutes": 24}]

Related MCP server: garmin-givemydata

health-assistant プロジェクトを統合

health-assistant プロジェクト（ローカル優先のパーソナルヘルスダッシュボード：Strava、睡眠、身体組成、食事分析）は本リポジトリに統合され、元のリポジトリはアーカイブされました。取り込まれたアセットは docs/health-assistant/ ディレクトリにあります：

• analytics.py —— 依存関係ゼロのトレーニング/回復サマリーとアドバイスエンジンのリファレンス実装（7日間のトレーニング統計、急性/慢性負荷比、レディネスチェック、毎日のトレーニングアドバイス）。

• coaching_methodology.md —— その背後にある説明可能なサイクリングコーチ、身体組成、スポーツ栄養の方法論。

• README.md —— 意図的に移植しなかった部分（FastAPI ダッシュボード、Strava OAuth/Webhook パイプライン、食事写真分析）とその理由を含む完全な移行説明。

このプロジェクトが行うこと

• 実験的な中国リージョンクラウドアダプターを通じて Xiaomi 運動健康データを読み取ります。

• 正規化されたレコードをローカル SQLite データベースに保存します。

• 認証情報を含まないポータブルな JSON または CSV をエクスポートします。

• 個人の自動化のためのローカル MCP クエリツールを公開します。

• 下流プロジェクト（個人の減量アドバイザーなど）向けに再利用可能なコネクタ実装を提供します。

意図的に医療アドバイス、減量指導、ホスト型アカウントアクセス、マルチユーザークラウドサービスは提供しません。

なぜこのブリッジを作ったのか？

対応データセット

• 毎日のアクティビティ：歩数、距離、アクティビティカロリー、アクティブ時間。

• 睡眠記録と睡眠ステージ。

• 運動記録。

• 身体測定：体重と利用可能な身体組成フィールド。

• 心拍数サンプル（利用可能な場合は安静時心拍数を含む）。

• 血中酸素（SpO2）、ストレス、異常心拍イベント（アカウント/デバイスが提供する場合）。

実際の利用可能性は、デバイス、アカウントのリージョン、ファームウェア、Xiaomi の上流サービスによって異なります。

インストール

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

Windows PowerShell：

.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

Windows Git Bash：

source .venv/Scripts/activate
pip install -e ".[dev]"

macOS/Linux：

source .venv/bin/activate
pip install -e '.[dev]'

設定

より安全な対話型設定パスにより、passToken をシェル履歴に直接書き込むことを避けられます：

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

利用可能な場合、認証情報はローカルキーチェーン（keyring）に保存されます。一部の代替 keyring 実装はキーを十分に安全でない方法で保存する場合があるため、使用前に OS の keyring の動作を理解してください。

user_id と passToken の取得方法

このブリッジは Xiaomi アカウントレベルの認証情報（米家アプリと同じログイン状態）を使用します。以下のいずれかの方法で取得できます：

方法1：ブラウザで手動コピー

1. ブラウザで account.xiaomi.com を開き、Xiaomi アカウント（Xiaomi 運動健康アプリと同じアカウント）にログインします。

2. 開発者ツール（F12）→「アプリケーション / Application」→ Cookies → https://account.xiaomi.com を開きます。

3. userId と passToken の2つの Cookie の値をコピーし、mi-fitness-bridge setup のプロンプトで貼り付けます。

方法2：QRコードログインツール

オープンソースの mijia-api で一度 QR コードログインします：

pip install mijiaAPI
python -c "from mijiaAPI import mijiaAPI; mijiaAPI().login()"   # 终端出二维码，用米家 App 扫码

ログイン状態はデフォルトで ~/.config/mijia-api/auth.json（Windows では %USERPROFILE%\.config\mijia-api\auth.json）に保存され、その中の userId と passToken をそのままこのブリッジに使用できます——Xiaomi アカウントレベルの認証情報はサービス間で共通であり、ブリッジはそれを使用して Xiaomi 運動健康（sid=miothealth）のセッションを取得します。auth.json は認証情報を平文で保存することに注意してください：userId と passToken をこのブリッジ（システムキーチェーン）に入力した後は、このファイルを削除することをお勧めします。

注意：

• passToken は期限切れになります。doctor が認証失敗を報告した場合は、上記の手順で再取得してください。

• ブラウザ方式は普段使用しているネットワーク環境でログインしてください。頻繁な操作や異なる場所からの操作は Xiaomi アカウントのリスク管理（スライダー/SMS 認証）を引き起こす可能性があります。リスク管理に遭遇した場合は QR コード方式を使用してください。

• Cookie 名とログインフローは 2026-08 の実測に基づいており、アカウントのリージョン、デバイス、リスク管理ポリシーによって異なる場合があります。また Xiaomi はプライベート API を随時変更する可能性があります（上部の実験的声明を参照）。

• これらの2つの値はアカウントのログイン状態と同等です。漏洩させず、Git にコミットしないでください。

同期

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

データベースはデフォルトでプラットフォームのユーザーデータディレクトリ（platformdirs が決定）に配置されます。sync、export、serve、doctor はすべて --db 引数または MI_FITNESS_DB_PATH 環境変数で場所を変更できます。優先順位：コマンドライン > 環境変数 > デフォルトの場所。platformdirs は Windows で LOCALAPPDATA 環境変数に応答しないことに注意してください。カスタムパスが必要な場合は上記の2つの方法を使用してください：

mi-fitness-bridge sync --db ./data/mi_fitness.db --start-date 2026-07-01 --end-date 2026-07-15
export MI_FITNESS_DB_PATH=./data/mi_fitness.db

既知の制限：日付引数なしの増分同期はローカルの最後のレコードの時刻を起点とし、上流の過去履歴の修正や補完は自動的に取得されません。必要に応じてより古い --start-date でその期間を明示的に再実行してください（冪等に上書きされ、重複レコードは生成されません）。

エクスポート

ポータブルな JSON ファイルを生成：

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

各データセットごとに CSV ファイルを生成：

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

エクスポートファイルには保存済みの Xiaomi passToken は決して含まれませんが、平文の user_id などの識別列は含まれます——エクスポートファイルは機密性の高い個人データであり、適切に保管してください。エクスポートされた健康記録はデフォルトで Git に無視されます。

エクスポート形式の説明（JSON エンベロープ構造、CSV レイアウト、閉区間の日付フィルタリングルール）は Export format を参照してください。

MCP サービス

互換コマンドは引き続き利用可能です：

mi-fitness-bridge serve
# legacy alias
mi-fitness-mcp serve

利用可能なツールには、接続状態、同期、カバレッジ、日次サマリー、身体測定、睡眠、運動、心拍数、血中酸素（SpO2）、ストレス照会、およびエージェント向けの workout_series 運動時系列ツールが含まれます——max_points のハード上限に従って自動ダウンサンプリング（固定時間バケット平均、SQLite 内集計）し、レスポンスで downsampled、source_points、returned_points、method を正直に示し、全精度統計（avg/min/max/分位数）と心拍数ゾーン時間も提供します。query_workouts、get_daily_summary などのリスト/サマリーツールには data_quality（カバー日数、欠落指標、最終同期時刻）が付属します。

クライアント接続例（Claude Code / Codex などの MCP クライアントの設定 JSON）：

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

注意：serve は stdio サービスであり、標準入出力を介してクライアントと通信します。HTTP サービスではありません。ターミナルで直接実行すると「フリーズ」しているように見えます——それはクライアントからの MCP メッセージを待っているだけで、正常な動作です。日常的には MCP クライアントに上記の設定で起動させてください。

Python 依存関係として使用

正規化アダプターは互換モジュール名で引き続き利用可能です：

from mi_fitness_mcp.adapters.mi_fitness_cloud import MiFitnessCloudAdapter

下流プロジェクトはコネクタソースコードを vendor 化したりコピーしたりせず、このパッケージをインストールしてください。

ライセンス

ライセンスの変遷：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 を参照してください。

プライバシーとセキュリティ

• passToken、ローカルデータベース、エクスポートファイル、ログを適切に保管し、外部に漏らさないでください。

• エクスポートファイルには passToken は含まれませんが、平文の user_id などの識別列が含まれるため、同様に機密性の高い個人データです。

• このブリッジを公開の認証情報プロキシとして実行しないでください。

• 実際の健康データや個人指標を含むスクリーンショットをコミットしないでください。

• バグレポートとドキュメントでは常に合成データを使用してください。

• 本ソフトウェアは個人データアクセスと工学研究のみを目的としており、診断や治療には使用されません。

責任ある開示方法は SECURITY.md、出典のトレーサビリティは THIRD_PARTY_NOTICES.md を参照してください。

開発

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

リリース

バージョン履歴は CHANGELOG.md、リリースおよびリリース後のチェック項目は docs/release-checklist.md を参照してください。

関連プロジェクト

• garmin-mcp —— ローカル優先の Garmin データ MCP サービス。本プロジェクトと agent-safe-series/v1 データ契約を共有しており（時系列ダウンサンプリングフィールドのセマンティクスがバイト単位で一致）、同じ AI エージェントが両サービスのデータをシームレスに消費できます。

このプロジェクトを支援する

このツールが役に立ったなら、GitHub でスターを付けてください。