mi-health-mcp

プロジェクト概要

mi-health-mcp は、現在ログインしている Xiaomi アカウント本人および承認済みの家族・友人の睡眠・心拍数・歩数を、MCP プロトコルを通じて Hermes などの MCP クライアントに提供します。サービスは Cloudflare Workers 上で動作します。本プロジェクトは wusaki0723/mi-health-mcp に由来し、GPL-3.0 ライセンスを保持し、Misty02600/mi-fitness-python と shkyyy18/mi_fitness_data_bridge のインターフェース実装を参考にしています。

Related MCP server: boyuan-health-bridge

デプロイ

Node.js 20 以降と Cloudflare アカウントが必要です。

git clone https://github.com/<your-github-account>/mi-health-mcp.git
cd mi-health-mcp
npm install
npx wrangler login
npx wrangler kv namespace create MI_HEALTH_KV

コマンド出力の namespace ID を wrangler.toml の kv_namespaces[0].id に書き込みます。KV namespace ID は Cloudflare のリソース識別子であり、アクセス資格情報ではありません。公開リポジトリでは、Workers Builds が Worker のエントリポイントと binding を認識できるよう、wrangler.toml をコミットする必要があります。Fork 後、デプロイ前に必ず自分のアカウントの namespace ID に置き換えてください。

次にアクセストークンを設定してデプロイします：

npx wrangler secret put AUTH_TOKEN
npx wrangler deploy

AUTH_TOKEN の値には自分で生成した長いランダム文字列を使用し、ソースコードや wrangler.toml、Git に書き込まないでください。

passToken ログイン

Xiaomi Account ブラウザ Cookie の userId、passToken、deviceId を Cloudflare Secret として設定することを推奨します。deviceId は通常 wb_ で始まります。Worker はこれらを使用して sid=miothealth の短期健康 API セッションを取得します。元の passToken は KV、ログ、MCP の戻り値には書き込まれません。

npx wrangler secret put XIAOMI_USER_ID
npx wrangler secret put XIAOMI_PASS_TOKEN
npx wrangler secret put XIAOMI_DEVICE_ID

Cloudflare Dashboard の Worker「Settings > Variables and Secrets」で同じ名前の Secret を追加することもできます。XIAOMI_USER_ID と XIAOMI_PASS_TOKEN は必ず同時に設定してください。XIAOMI_DEVICE_ID は任意で、設定する場合はその passToken を取得したときと同じブラウザセッションの deviceId を使用してください。

KV binding 名は MI_HEALTH_KV のままにしてください。AUTH_TOKEN、XIAOMI_USER_ID、XIAOMI_PASS_TOKEN は Cloudflare Secret を使用し、ソースコード、設定ファイル、Git に書き込まないでください。

Hermes 設定

mcp_servers:
  mi_health:
    url: "https://<worker-name>.<account-subdomain>.workers.dev/mcp"
    headers:
      Authorization: "Bearer ${MI_HEALTH_AUTH_TOKEN}"

URL は自分でデプロイした Worker のアドレスに置き換えてください。MI_HEALTH_AUTH_TOKEN の値はその Worker の AUTH_TOKEN Secret と一致している必要があります。例には実際の資格情報は含まれていません。

Hermes skill

リポジトリ内の skills/mi-health/SKILL.md は、「私/本人」と「家族・友人」のリクエストを適切なツールに振り分け、簡潔な結果のフィールドの意味を説明します。リポジトリが公開された後、元のファイル URL からインストールできます：

hermes skills install https://raw.githubusercontent.com/<your-github-account>/mi-health-mcp/main/skills/mi-health/SKILL.md
hermes skills list

skill は自動的にスケジュールタスクを作成しません。既存のタスクに接続する場合は、まずタスクと最近の実行記録を確認し、タスク ID を指定して追加します：

hermes cron status
hermes cron list
hermes cron runs <job-id>
hermes cron edit <job-id> --add-skill mi-health

スケジュールタスクは独立したセッションで実行されるため、prompt にはクエリ対象、日数、タイムゾーン、送信先、失敗時の処理方法を明確に指定する必要があります。prompt に資格情報を入れないでください。定期タスクでは provider と model を固定し、グローバルなデフォルト値の変更による動作変化を避けてください。

利用フロー

1. XIAOMI_USER_ID と XIAOMI_PASS_TOKEN を設定した後、health_login_refresh を呼び出します。XIAOMI_DEVICE_ID は任意の Secret で、必要に応じてその passToken を取得したブラウザセッションを指定するために使用します。Worker は miothealth セッションを取得してキャッシュします。失敗した場合、現在のキャッシュセッションは削除されません。

2. health_me で現在のアカウントを確認します。単一の生のサマリーをクエリする場合は health_latest、health_sleep、health_heart、health_steps を呼び出し、トレンド分析が必要な場合は health_analyze を優先して呼び出し、ユーザーの現在の IANA タイムゾーンを渡します。

3. 家族・友人をクエリする場合は、まず health_relatives を呼び出し、次に target: "relative" と返された relative_uid を渡します。

health_login_start と health_login_poll は互換性のためだけに残されています。この QR コードフローは一部のアカウントで Xiaomi に拒否され 70036 が返されることがあり、小米运动健康 App も QR コードがサポートされていないと表示する場合があります。本プロジェクトではこれを検証済みの利用可能なログイン方法とは説明していません。

健康クエリのデフォルトは target: "self" で、本人のデータインターフェースを使用し、relative_uid は送信されません。家族・友人のクエリでは有効な relative_uid を必ず指定する必要があり、家族・友人リストの最初の項目が自動的に選択されることはありません。

MCP tools

• health_me：現在のログイン状態と user_id を返します。資格情報は返しません。

• health_login_status：現在の健康 API セッションが利用可能かどうかとログイン方法を返します。資格情報は返しません。

• health_login_refresh：Xiaomi アカウントの Secret を使用してセッションを強制的に更新します。失敗した場合は既存のキャッシュセッションを保持します。

• health_relatives：クエリ可能な家族・友人の relative_uid とメモを一覧表示します。

• health_latest：最新の睡眠・心拍数・歩数のサマリーをクエリします。

• health_analyze：デフォルトで 30 日間をクエリし、直近 7 つの完全な日とそれ以前の記録から個人ベースラインを確立します。未終了の当日アクティビティを分離し、欠落日、同期遅延、睡眠ステージの完全性、心拍数サンプリング品質を報告し、非診断的な robust statistics を出力します。

• health_sleep：直近 1〜30 日間の毎日の睡眠サマリーをクエリします。1 日あたり最大 1 件です。

• health_heart：直近 1〜30 日間の毎日の心拍数統計をクエリします。すべてのサンプルポイントは返しません。

• health_steps：直近 1〜30 日間の毎日の歩数サマリーをクエリします。1 日あたり最大 1 件です。

本人をクエリする場合は target を省略するか、明示的に {"target":"self"} を渡します。家族・友人をクエリする場合は必ず以下を渡します：

{
  "target": "relative",
  "relative_uid": "...",
  "days": 7
}

トレンド分析の例：

{
  "target": "self",
  "days": 30,
  "recent_days": 7,
  "timezone": "Europe/Berlin"
}

health_analyze は健康 API がすでに返した日付を再計算しません。timezone は現在の自然日を識別するためだけに使用され、当日の歩数と毎日の心拍数を partial とマークし、完全な日のベースラインから除外します。睡眠は起床日基準で完了した記録とみなされます。同じ日付に重複するサマリーがある場合、アナライザーは有効な測定、サンプリングまたは睡眠ステージの完全性、記録時間、安定キーに基づいて決定的に 1 つを選択します。recent_days は直近の自然日のウィンドウを表します。欠落または品質不足で除外された日付は、より古い記録で補完されません。結果は最初に data_quality を返します：missing_dates はその日の記録が欠落していることを示し、missing_measurements は記録は存在するが対象の値が空、非数値、または負数であることを示します。どちらも 0 ではなく不明として扱われます。結果は最新のデータ同期遅延、睡眠ステージの完全率、心拍数サンプリング品質も報告します。完全な日のサンプル数中央値の 50% 未満の日付は low_sample_dates にリストされ、有効なサンプル数がない日付は unknown_sample_dates にリストされます。どちらも心拍数トレンドには入りません。トレンド比較では丸めていない median、MAD、IQR、robust z-score を使用し、出力時にのみ丸めます。サンプルが不十分な場合は insufficient_data を返し、無理にトレンド結論を出しません。すべての比較は個人の履歴サマリーであり、疾病診断や投薬アドバイスには使用できません。

利用上の制限

自分の Xiaomi アカウントにログインし、承認済みの家族・友人のデータをクエリするためだけに使用してください。他人のプライバシーを侵害したり、Xiaomi のユーザー契約に違反する用途には使用しないでください。

本人データは POST /app/v1/data/get_fitness_data_by_time を使用します。中国リージョンではクエリウィンドウの前後をそれぞれ 18 時間拡張し、記録の zone_offset に従って日付に分類します。zone_offset がない場合は UTC+8 にフォールバックします。本人の steps 記録はインターフェースの増分セマンティクスに従って日ごとに集計します。本人の heart サンプルポイントは毎日の統計に変換されます。sleep は同じ日に、非昼寝で、継続時間が長く、更新時刻が新しい記録を優先します。家族・友人のデータは /app/v1/relatives/* の daily_report を使用し、同じ日の記録を重複して合計しません。

MCP の戻り値はフィールドホワイトリストを使用し、AUTH_TOKEN、passToken、cUserId、serviceToken、ssecurity、Cookie を返しません。.dev.vars、.env、wrangler.toml、.wrangler/ をコミットしないでください。

ライセンス

本プロジェクトは GNU General Public License v3.0（GPL-3.0）を採用しており、上流の Misty02600/mi-fitness-python のライセンスと一致しています。