google-health-mcp

google-health-mcp

适用于 Google Health API 的 MCP 服务，配备本地 SQLite 缓存和趋势分析功能。

专为 Claude Code 及其他 MCP 客户端打造。数据会同步到你本机上的数据库，因此查询速度快、支持离线使用，也不会消耗 API 配额。

功能

• 本地 SQLite 缓存 - 只需同步一次，即可即时查询
• 增量同步 - 每次运行只获取新增数据，并从上次停止的位置继续
• 离线模式 - 无需凭据或网络连接，即可提供缓存数据
• 趋势 - 按周、月或季度汇总，并支持比较两个时段
• ECG - 完整存储读数，包括波形；仅在请求时返回
• doctor - 离线、只读地诊断设置情况，不消耗配额

数据类型

工具	数据
health_get_heart_rate	静息心率
health_get_activity	步数、卡路里、距离、楼层数
health_get_exercises	锻炼：名称、时长、心率、卡路里、Google 指标摘要，以及按需提供的分段数据
health_get_exercise_route	单次锻炼的 GPS 路线，即 Google 导出的 TCX 文件
health_get_sleep	睡眠时长、阶段、睡眠时段
health_get_sleep_sessions	Google 记录的每次睡眠：元数据、摘要，以及按需提供的每个阶段片段
health_get_weight	体重、体脂率，每天一条记录
health_get_weight_readings	Google 记录的每次称重和体脂读数
health_get_height	身高读数
health_get_spo2	每晚血氧饱和度
health_get_hrv	心率变异性（RMSSD）
health_get_azm	活动区间分钟数及各区间明细
health_get_breathing_rate	每晚呼吸频率（次/分钟）
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+（在 Linux、macOS 和 Windows 上使用 3.13 和 3.14 进行过测试，并通过 CI 验证）
• 拥有健康数据的 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 客户端。需要在控制台中完成七个步骤，以下页面名称截至 2026 年 8 月为 Google 使用的名称。

**Google 自己的设置页面会把你引到别处——请改为遵循以下步骤。**该页面的快速入门会创建一个 Web 客户端，并将 https://www.google.com 设为重定向 URI。这适用于 OAuth Playground，而不适用于在你的机器上运行的程序；本服务会拒绝该文件，并说明原因。仅将该页面用于确认下方某个页面是否已更名。

1. **项目。**在 console.cloud.google.com/projectcreate 创建项目并选中它。
2. **API。**在 API 启用页面启用 Google Health API。
3. **开始使用。**打开 Google Auth Platform 并完成 开始使用：应用名称、支持邮箱、External 受众群体、联系邮箱。新项目在完成此步骤之前不会有 Audience、Data Access 或 Clients 页面。
4. **受众群体。**在 测试用户下添加你自己的 Google 账号。跳过此步骤会导致登录失败，并显示 403: access_denied。
5. **数据访问。**点击 添加或移除范围，搜索“Google Health API”，并勾选下方OAuth 范围中列出的只读范围。
6. **客户端。**创建 桌面应用类型的 OAuth 客户端并下载其 JSON。桌面客户端会自动允许环回重定向，因此无需注册；Web 客户端则不会，并会在授权确认时失败。
7. **发布。**返回 Audience 页面，点击 发布应用。

**第 7 步最容易出问题，值得确认，而不是想当然。**当应用的发布状态为 Testing 时，Google 颁发的刷新令牌会在授权后七天过期——所以一开始一切正常，但一周后同步就会停止，而且没有任何提示能让你想到这个原因。Audience 页面可能显示“In production”，但令牌服务器给出的结果却不同。以下两处显示的信息不会出错：Branding 页面上的验证状态行，以及 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 报告该账号未关联 Google Health，它会说明情况并以状态码 1 退出。再次运行并选择另一个账号即可。

此流程会在 localhost:8081 上监听回调，因此该端口必须空闲。令牌会保存到 ~/.config/google-health-mcp/google_tokens.json，在 POSIX 系统上创建时权限为 0600。Windows 仅保留所有者写入位，将其作为只读属性，并通过 ACL 控制访问权限——因此在 Windows 上，该文件并不只对你的账号开放；它实际授予的权限取决于其目录 ACL 所传递的权限。访问令牌有效期为一小时，并会自动刷新。刷新令牌不会轮换，因此可以将在带浏览器的机器上生成的令牌复制到无头机器上。

如果你在发布应用之前就已授权，请在发布后重新运行 google-health-mcp auth：发布不会延长已授予令牌的有效期，该令牌仍会在七天后过期。

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 是否可以绑定，以及此主机是否可以打开浏览器，这两种情况都会导致 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}
}

负载会写入 stdout；日志会写入 stderr，因此 subprocess 消费端应分别读取两者。

请按 check 匹配，绝不要按 name 或 detail 匹配：前者是稳定标识符，后两者是文本描述，并携带数据类型。对于目前尚无程序化消费方的检查结果，check 为 null。

只有当某项结果的评级为 fail 时，退出代码才为 1，两种格式均如此——警告不会改变退出代码。这正是此标志存在的原因：数据序列中断属于警告，因此仅凭退出代码无法判断那个最值得关注的故障。

在信任缺少的 check 之前，请先检查 version。 比当前版本更旧的发行版会完全省略此字段，而更旧的版本甚至会拒绝 --json 并以 2 退出，因此“没有 stopped-series 检查结果”和“此构建无法报告该检查结果”看起来完全相同。若软件包是从没有已安装发行版元数据的源代码树运行，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 除外，其默认值为最近十年。
• 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 才会返回路线文本，因为它可能达到数百 KB。只有通过 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）。后续同步为增量同步。
• since / until - 获取精确的时间范围，无论缓存中已有何种数据。

同步只会添加和修正数据，不会删除数据。 在记录数据的应用中删除某条记录后，它只会从 API 中消失，不会留下任何表明其已删除的信息，因此重新同步该时间范围时，缓存中的行会保持原样。API 不提供墓碑记录、变更订阅源或按修改时间筛选的功能，因此无从检测这类删除。实际上，这只会影响需要手动填写的数据类型，因为设备记录的数据序列不会事后删除。要清除数据，必须重新创建缓存。

health_trends

• data_type - 任何带有每日序列的已缓存类型；ECG 读数和心律告警属于事件，睡眠时段和单条读数属于记录，因此没有趋势。默认值：activity。
• period - weekly、monthly、quarterly。默认值：monthly。
• start_date / end_date - 默认值：最近 12 个月。
• compare - 两个时段，例如 last_30d vs previous_30d、2026-03 vs 2026-02、2026-Q1 vs 2025-Q4。设置后，period、start_date 和 end_date 将被忽略。

OAuth scopes

在 Data Access 页面勾选这些只读作用域。它们都位于 https://www.googleapis.com/auth/googlehealth. 下：

Scope	访问的数据
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 中移除相应项目；这需要检出源代码，而不能通过 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。

典型用途：

• 多台机器共用一个缓存 - 一台主机通过 cron 或 systemd 运行 google-health-mcp sync，并使用共享数据库；其他主机设置 GOOGLE_HEALTH_MCP_OFFLINE=1，将 GOOGLE_HEALTH_MCP_DB_PATH 指向同一文件，仅进行读取。
• CI 和隐私保护 - 在没有网络访问和凭据的情况下运行查询。

速率限制

Google 对每位用户实施请求配额，详见 developers.google.com/health/rate-limits。常规同步远未达到配额上限：一天的更新只需少量请求；实测中，对所有数据类型进行为期三年的回填约需 250 次请求。如果同步中途停止，该数据类型会被记录为部分同步；下次运行时会从游标处继续，而不是从头开始。

从缓存查询（默认行为）完全不消耗配额。

数据安全

您的健康数据保留在本机：此服务没有后端，不会向任何地方发送数据，只会使用您自己的凭据与 Google 的 API 通信。

此代码库提供了一个 pre-commit 钩子，会阻止提交数据库文件、config/ 下的任何内容以及大型文件；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。导入涵盖这七种类型；其他所有数据都通过 sync 获取。

贡献

开发环境设置、测试工作流和 pre-commit 钩子请参阅 CONTRIBUTING.md。更改记录见 CHANGELOG.md。

许可证

GPL-3.0-or-later