google-health-mcp

google-health-mcp

Google Health API 用の MCP サーバーです。ローカルの SQLite キャッシュとトレンド分析機能を備えています。

Claude Code やその他の MCP クライアント向けに設計されています。データはご自身のマシン上のデータベースに同期されるため、クエリは高速で、オフラインでも動作し、API クォータも消費しません。

機能

• ローカル SQLite キャッシュ - 一度同期すれば、すぐにクエリできます
• 増分同期 - 実行するたびに新しいデータだけを取得し、前回の停止位置から再開します
• オフラインモード - 認証情報もネットワーク接続も使わずにキャッシュを利用できます
• トレンド - 週次、月次、四半期ごとの集計と、2 期間の比較に対応します
• 心電図 - 波形を含む測定値全体を保存し、リクエストされた場合にのみ返します
• doctor - クォータを消費せず、オフラインかつ読み取り専用でセットアップを診断します

データの種類

ツール	データ
health_get_heart_rate	安静時心拍数
health_get_activity	歩数、カロリー、距離、階数
health_get_exercises	ワークアウト：名称、時間、心拍数、カロリー、Google の指標サマリー、およびリクエスト時のスプリット
health_get_exercise_route	1 回分のワークアウトの GPS ルート。Google がエクスポートする TCX ファイル形式
health_get_sleep	睡眠時間、ステージ、睡眠時間帯
health_get_sleep_sessions	Google が記録した各セッションのメタデータとサマリー、およびリクエスト時のすべてのステージ区間
health_get_weight	体重、体脂肪率。1 日につき 1 行
health_get_weight_readings	Google が記録したすべての体重測定値と体脂肪測定値
health_get_height	身長の測定値
health_get_spo2	夜間の血中酸素飽和度
health_get_hrv	心拍変動（RMSSD）
health_get_azm	アクティブゾーン時間とゾーンごとの内訳
health_get_breathing_rate	夜間の 1 分あたりの呼吸数
health_get_skin_temperature	夜間の基準値からの変動と、その根拠となる絶対値
health_get_core_temperature	手動で記録した体温測定値
health_get_cardio_fitness	デバイスが報告する場合の VO2 最大値
health_get_food_log	記録されている食事のカロリーと水分量
health_get_ecg	心電図：分類、平均心拍数、時間、およびリクエスト時の波形
health_get_irregular_rhythm	不整脈の通知と、その通知を引き起こした時間帯
health_get_devices	ペアリング済みデバイス、バッテリー残量、最終同期時刻
health_get_profile	Google が返すプロフィール、設定、不整脈登録状況
health_get_lifetime_stats	キャッシュ内の履歴全体における合計と最高記録の日、およびそのカバー範囲
health_trends	集計された平均値と期間比較

要件

• Python 3.13+（CI では Linux、macOS、Windows 上の 3.13 および 3.14 でテスト済み）
• 健康データを含む Google アカウントと、認証に使用する Google Cloud プロジェクトが必要です。課金アカウントは不要です - セットアップ中、コンソールには無料トライアルが表示されますが、すべて辞退できます。

セットアップ

1. インストール

pip install google-health-mcp

インストールせずに実行することもできます。その場合、以下で実行する google-health-mcp ... コマンドはすべて uvx google-health-mcp ... になります。

uvx google-health-mcp --version

2. Google Cloud プロジェクトを作成する

各ユーザーが独自の OAuth クライアントを登録します。コンソールでの手順は 7 ステップです。ページ名は 2026 年 8 月時点の Google のものです。

Google のセットアップページでは別のページに案内されます。代わりに、以下の手順に従ってください。 クイックスタートでは、リダイレクト URI に https://www.google.com を指定した Web クライアントが作成されます。これは OAuth Playground には適していますが、マシン上で実行するプログラムには適していません。このサーバーはそのファイルを受け付けず、その旨を表示します。以下のページ名が変更されていないか確認する場合に限り、このページを参照してください。

1. プロジェクト。 console.cloud.google.com/projectcreate でプロジェクトを作成し、選択します。
2. API。 API の有効化ページで Google Health API を有効にします。
3. 開始。 Google Auth Platform を開き、開始を完了します。アプリ名、サポート用メールアドレス、外部の対象ユーザー、連絡先メールアドレスを入力します。新しいプロジェクトでは、これを完了するまで「対象ユーザー」「データアクセス」「クライアント」のページはありません。
4. 対象ユーザー。 テストユーザーで、自分の Google アカウントを追加します。省略すると、サインインに失敗し、403: access_denied が表示されます。
5. データアクセス。 スコープを追加または削除をクリックし、「Google Health API」を検索して、以下のOAuth スコープに記載されている読み取り専用のスコープにチェックを入れます。
6. クライアント。 タイプが デスクトップアプリの OAuth クライアントを作成し、その JSON をダウンロードします。デスクトップクライアントではループバックリダイレクトが自動的に許可されるため、登録は不要です。一方、Web クライアントでは許可されず、同意画面で失敗します。
7. 公開。 対象ユーザーのページに戻り、アプリを公開をクリックします。

問題になるのはステップ 7 です。決めつけず、確認する価値があります。 アプリの公開ステータスが「テスト中」の間、Google は同意から 7 日後に期限切れとなるリフレッシュトークンを発行します。そのため、すべて正常に動作した後、1 週間後に同期が止まっても、この時点を示すものは何もありません。対象ユーザーのページに「本番環境」と表示されていても、トークンサーバーの判断は異なることがあります。食い違いを示すのは、ブランディングページの確認ステータス行と、保存されたトークンに短い有効期限が記録されている場合に明確なエラーを出す google-health-mcp doctor です。

3. 認証する

ダウンロードしたクライアント JSON を編集せずに、サーバーが参照する場所に配置します。

mkdir -p ~/.config/google-health-mcp
cp ~/Downloads/client_secret_*.json ~/.config/google-health-mcp/google_client.json
google-health-mcp auth

ブラウザーに Google はこのアプリを確認していませんという警告が表示されます。これは想定どおりです。アプリは自分自身のものです。これらのヘルススコープは制限付きに分類されており、確認が必要なのはユーザー数が 100 人を超える場合のみです。詳細をクリックし、google-health-mcp（安全ではないページ）に移動を選択して、スコープを許可します。

Google アカウントを複数持っている場合は、ヘルスデータがあるアカウントを選択してください。auth はトークンの保存後にアカウントを確認します。Google Health にリンクされていないと報告された場合は、その旨を表示して終了コード 1 で終了します。再度実行して、別のアカウントを選択してください。

このフローはコールバックを受信するために localhost:8081 をリッスンするので、このポートが空いている必要があります。トークンは ~/.config/google-health-mcp/google_tokens.json に保存され、POSIX では 0600 で作成されます。Windows では所有者の書き込みビットのみが読み取り専用属性として保持され、アクセスは ACL で制御されます。そのため、Windows ではファイルは自分のアカウントだけに制限されず、アクセス権はそのディレクトリから継承される ACL によって決まります。アクセストークンの有効期間は 1 時間で、自動的に更新されます。リフレッシュトークンはローテーションされないため、ブラウザーのあるマシンで発行されたトークンを、ヘッドレスマシンにコピーできます。

アプリを公開する前に認証した場合は、その後 google-health-mcp auth を再実行してください。公開しても、すでに付与されたトークンの有効期限は延長されず、そのトークンは引き続き 7 日後に期限切れになります。

4. MCP クライアントに登録する

claude mcp add -s user google-health -- google-health-mcp

代わりに uvx で実行する場合：claude mcp add -s user google-health -- uvx google-health-mcp。

5. 確認する

google-health-mcp doctor

ステップ 3（認証）の前と後の両方で実行すると便利です。ポート 8081 をバインドできるか、このホストでブラウザーを開けるかを報告します。この 2 つは、auth が起動前に失敗する原因です。

オフラインかつ読み取り専用で、各パスがどこに解決されたか、認証情報ファイルの形式が正しいか、トークンの有効期間が短いか、許可された権限にこのバージョンが読み取るすべての権限が含まれているか、キャッシュが最新の状態に保たれているかを報告します。

doctor --json は、監視システムが処理できるように、同じ診断結果を報告します。

{
  "version": "1.9.0",
  "findings": [
    {
      "check": "stopped-series",
      "name": "hrv series",
      "severity": "warn",
      "detail": "No hrv since 2026-03-30, after rows on 28 of the 30 days before that.",
      "fix": "Re-sync that type alone (...)"
    }
  ],
  "counts": {"ok": 7, "warn": 1, "fail": 0}
}

ペイロードは標準出力に出力され、ログは標準エラー出力に出力されるため、subprocess の利用側はそれぞれを別々に読み取る必要があります。

照合には name や detail ではなく、必ず check を使ってください。check は安定した識別子ですが、ほかの 2 つは説明文であり、データ型も含んでいます。まだプログラムで利用されていない診断結果では、check は null です。

**終了コードが 1 になるのは、どちらの形式でも、何かが fail と評価された場合だけです。**警告によって終了コードが変わることはありません。これがこのフラグがある理由です。データ系列の停止は警告なので、終了コードだけでは、最も注意すべき 1 つの失敗を判断できません。

**check がない場合は、version を確認してから判断してください。**このリリースより古いバージョンではこのフィールドが省略され、さらに古いバージョンでは --json が拒否されて終了コード 2 で終了します。そのため、stopped-series の診断結果がない場合と、このビルドでは報告できない場合は、version がなければ区別できません。インストール済みのディストリビューションメタデータがないソースツリーからパッケージを実行した場合、version 自体が null になります。設定が不完全なインストールで診断が失敗するのは、まさに必要なときに役に立たないため、ペイロードは引き続き出力されます。

ペイロードには、テキストレポートと同じように、解決された設定、データベース、認証情報の各パスが記載されます。これは、誤ったパス設定の診断を可能にするためです。ただし、ペイロードをマシンの外部に転送する利用側は、これらの情報を開示することになります。どちらの形式にも、認証情報の 値 は含まれません。

6. 初回同期（任意）

クエリツールは毎日初めて使用するときに同期するため、この手順は省略できます。キャッシュに事前にデータを格納する場合や、それより古い履歴を取得する場合は、次のコマンドを実行します。

google-health-mcp sync --days 30
google-health-mcp sync --since 2023-10-01     # backfill

CLI の使い方

google-health-mcp                Start the MCP server (stdio transport)
google-health-mcp -V, --version  Print the installed package version
google-health-mcp auth           Interactive OAuth setup
google-health-mcp doctor         Check the setup and report what needs fixing
  --json                Emit the findings as JSON, for a monitor rather than
                        a person. Each finding carries a stable `check` name
                        to match on; the exit code is the same either way.
google-health-mcp sync           Sync data to the local cache
  --days N              Days of history for a first sync (default: 30)
  --types TYPE,...      Data types to sync (default: all). One or more of:
                        heart_rate, activity, exercises, sleep, weight, spo2,
                        hrv, azm, breathing_rate, skin_temperature,
                        core_temperature, cardio_fitness, food_log, ecg, irn,
                        account, height, exercise_routes, sleep_sessions,
                        weight_readings, body_fat_readings
  --since YYYY-MM-DD    Fetch from this date, ignoring the incremental cursor
  --until YYYY-MM-DD    Inclusive end date for a --since window; together they
                        re-fetch exactly that window, to repair a gap in the
                        middle of the cache
google-health-mcp import         Import exported JSON data files
  --data-dir PATH       Directory containing the JSON files

MCP ツールリファレンス

クエリツールは、データ型ごとにその日の最初のクエリで同期し、その後はキャッシュを読み取ります。

health_get_devices、health_get_lifetime_stats、health_get_profile、health_get_exercise_route を除くすべてのクエリツールは、次の引数を受け取ります。

• start_date - YYYY-MM-DD、YYYY-MM、または 30d（相対指定）。デフォルトは過去30日間です。ただし、health_get_height のデフォルトは過去10年間です。
• end_date - YYYY-MM-DD。デフォルトは今日です。
• live - true の場合、キャッシュを読み取る前に、この期間のデータを API から再取得します。更新に失敗した場合は、キャッシュから黙って回答するのではなく、その旨が報告されます。

health_get_profile が受け取るのは live のみです。

health_get_exercises は、ワークアウト名に対する大文字と小文字を区別しない部分一致の exercise_type も受け取ります。ワークアウト名は Google が付けるため、キャッシュ内のどのワークアウト名にも一致しない値を指定すると、その期間にトレーニングしていないものとして回答するのではなく、キャッシュ内の名前と live=True のヒントが表示され、リクエストは拒否されます。また、include_detail も受け取ります。これを指定しない場合、各ワークアウトについて、すべてのイベント、スプリット、スプリット概要ではなく、それぞれの件数が返されます。health_get_ecg は include_waveform も受け取ります。波形データは数千件の電圧値に及ぶため、デフォルトのレスポンスには分類、平均心拍数、継続時間、サンプル数のみが含まれます。health_get_sleep_sessions は同じ理由で include_stages も受け取ります。これを指定しない場合、各セッションについて、すべての睡眠段階セグメント、短時間の覚醒、ベッドから出ていたセグメントではなく、それぞれの件数が返されます。

health_get_exercise_route は、ワークアウトの log_id を受け取ります。ルートのテキストが返されるのは include_tcx を指定した場合のみです。テキストが数百キロバイトに及ぶことがあるためです。ルートがあるのは GPS で記録したワークアウトのみです。また、同期ではその期間内のワークアウトのルートが取得されるため、古いルートには data_types="exercise_routes" と since を指定して health_sync を実行する必要があります。ルートには、開始地点と終了地点を含む、記録されたすべての位置情報が含まれます。ほかのデータと同様にディスク上にキャッシュされ、include_tcx を指定した場合にのみモデルに渡されます。

このバージョンが読み取る権限を認可で許可されていない場合、成功したツールレスポンスには該当する権限名を示す authorisation の注記が含まれ、doctor は missing-scopes チェックで報告し、sync はその内容を出力します。 該当するデータ型は失敗扱いではなくスキップされるため、sync は引き続き終了コード 0 で終了します。認可を更新しても権限は追加されないため、権限を追加するアップグレード後に google-health-mcp auth を再実行するまでは、このような状態になります。同期を実行するホスト上の doctor には新しい認可がすぐに反映されます。ツールの注記と、キャッシュのみを使用するホスト上の doctor には、次回の同期後に反映されます。新たに許可されたデータをすぐに取得するには、認可後に google-health-mcp sync を実行してください。そうしない場合、スキップされた型もその日の同期済みとして扱われるため、クエリツールは翌日まで待機します。

health_sync

• data_types - all、または上記の CLI の使い方 に記載された名前のカンマ区切りのサブセット（irn は不規則な心拍の通知、account はプロフィール、設定、不規則な心拍の登録情報です）。デフォルトは all です。
• days - 初回同期で取得する履歴の日数（デフォルト：30）。2回目以降の同期は差分同期です。
• since / until - キャッシュの内容にかかわらず、指定した期間のデータを取得します。

同期ではデータが追加・修正されますが、削除されることはありません。 データを記録したアプリでエントリを削除すると、削除されたことを示す情報がないまま API に表示されなくなります。そのため、該当期間を再同期しても、キャッシュ内の行はそのまま残ります。API には削除を示す記録も、変更フィードも、更新日時で絞り込むフィルターもないため、削除を検出する方法はありません。実際には、後からデバイスの記録系列が削除されることはないため、この問題が生じるのは手動で入力するデータ型に限られます。キャッシュを消去するには、作り直す必要があります。

health_trends

• data_type - 日単位の系列があるキャッシュ済みの任意のタイプです。ECG の測定値とリズムアラートはエピソード、睡眠セッションと個々の測定値はレコードであり、トレンドはありません。デフォルト：activity。
• period - weekly、monthly、quarterly。デフォルト：monthly。
• start_date / end_date - デフォルトは過去12か月です。
• compare - 2つの期間を指定します（例：last_30d vs previous_30d、2026-03 vs 2026-02、2026-Q1 vs 2025-Q4）。設定すると、period、start_date、end_date は無視されます。

OAuth スコープ

Data Access ページで、以下の読み取り専用スコープにチェックを入れてください。すべて https://www.googleapis.com/auth/googlehealth. 配下にあります。

Scope	Data accessed
activity_and_fitness.readonly	歩数、距離、階数、カロリー、ワークアウト、アクティブゾーン時間
health_metrics_and_measurements.readonly	心拍数、HRV、SpO2、呼吸数、体重、体脂肪率、身長、体温、VO2 max
sleep.readonly	睡眠セッションと睡眠ステージ
nutrition.readonly	食事と水分の記録
ecg.readonly	心電図
irn.readonly	不規則なリズムの通知と登録
settings.readonly	ペアリング済みデバイス、単位、タイムゾーン
profile.readonly	年齢、メンバーシップ開始日、歩幅
location.readonly	ワークアウトの GPS ルート

コンソールには reproductive_health.readonly、logged_symptoms.readonly、mindfulness.readonly もありますが、このパッケージではリクエストしません。2026年9月時点では、月経周期、排卵検査、症状、気分のデータタイプは書き込み可能ですが読み取りはできず、API にマインドフルネスのデータタイプはありません。そのため、これらのスコープで読み取れるデータはありません。

公開されているスコープのページではなく、コンソールに表示される一覧を確認してください - Google のドキュメントにも API 自身のディスカバリードキュメントにも記載されていない読み取り専用スコープがあり、ディスカバリードキュメントには nutrition.readonly がまったく記載されていません。リクエストするスコープを減らすには、Data Access ページでチェックを外し、認証前に config.py の GOOGLE_SCOPE_READERS からも削除してください。これは pip または uvx によるインストールではなく、ソースコードをチェックアウトして行う必要があります。除外したスコープに属するデータタイプは、すべての同期でスキップされます。許可されたスコープはトークンの更新時に追加されないため、後から一覧を拡張する場合は、あらためて auth を実行してください。

設定

Variable	Default	Description
GOOGLE_HEALTH_MCP_CONFIG_DIR	~/.config/google-health-mcp/	OAuth クライアントとトークンを格納するディレクトリ
GOOGLE_HEALTH_MCP_DB_PATH	~/.local/share/google-health-mcp/google_health.db	SQLite キャッシュ
GOOGLE_HEALTH_MCP_OFFLINE	未設定	真偽値として評価される値（1、true、yes、on）の場合、キャッシュのみを読み取るモードで実行します

オフライン／キャッシュのみのモード

デフォルトでは、サーバーは要求に応じて同期するため、cron ジョブは不要です。純粋な読み取り専用で実行するには、GOOGLE_HEALTH_MCP_OFFLINE=1 を設定します。

• 認証情報は不要です - サーバーはトークンファイルを開きません。
• ネットワーク呼び出しは行われません。自動同期は無効になり、live=True、health_get_devices、health_sync は API にアクセスせず、「オフラインモード」であることを明確に示すメッセージを返します。
• クエリツールはキャッシュを提供し、"offline_mode": true のタグが付きます。

一般的な用途：

• 複数のマシンで1つのキャッシュを共有 - 1台のホストで cron または systemd から google-health-mcp sync を実行し、共有データベースと同期します。他のマシンでは GOOGLE_HEALTH_MCP_OFFLINE=1 を設定し、GOOGLE_HEALTH_MCP_DB_PATH を同じファイルに指定して、読み取り専用で使用します。
• CI とプライバシー - ネットワークアクセスや認証情報なしでクエリを実行します。

レート制限

Google はユーザー単位のリクエストクォータを適用しています。詳細は developers.google.com/health/rate-limits に記載されています。通常の同期で上限に達することはまずありません。1日分の更新に必要なリクエストは数件であり、すべてのデータタイプを対象とした3年間のバックフィルを計測したところ、リクエスト数は約250件でした。同期が途中で中断された場合、そのデータタイプは部分同期として記録され、次回の実行では最初からやり直さず、カーソルから再開します。

デフォルトのキャッシュからのクエリでは、クォータを一切消費しません。

データの安全性

健康データはお使いのマシン内に留まります。このサーバーにはバックエンドがなく、データを外部に送信することもありません。お客様自身の認証情報を使って Google の API とだけ通信します。

このリポジトリには、データベースファイル、config/ 以下のファイル、大容量ファイルのコミットを拒否する pre-commit フックが含まれています。インストール方法はCONTRIBUTING.mdをご覧ください。

既存データのインポート

エクスポートデータや独自のスクリプトから取得した健康データが JSON ファイルとしてすでにある場合は、次のようにします。

google-health-mcp import --data-dir /path/to/json/files/

想定されるファイル名は、heart_rate.json、activity.json、exercises.json、sleep.json、weight.json、spo2.json、hrv.jsonです。それぞれのファイルで想定される形式については、src/google_health_mcp/importer.pyをご覧ください。インポートに対応しているのはこの 7 種類です。それ以外のデータはsyncで取得されます。

コントリビューション

開発環境のセットアップ、テストのワークフロー、pre-commit フックについてはCONTRIBUTING.mdをご覧ください。変更履歴はCHANGELOG.mdで確認できます。

ライセンス

GPL-3.0-or-later