google-health-mcp

面向 Google Health API 的 MCP 服务器，带有本地 SQLite 缓存和趋势分析功能。

专为 Claude Code 和其他 MCP 客户端设计。您的数据会同步到您自己机器上的数据库中，因此查询速度快、支持离线使用，且不消耗任何 API 配额。

功能特性

• 本地 SQLite 缓存 - 同步一次，即时查询

• 增量同步 - 每次运行只获取新增数据，从上次停止的地方继续

• 离线模式 - 无需凭据、无需网络即可使用缓存

• 趋势分析 - 按周、月、季度聚合，以及双周期对比

• 心电图 (ECG) - 完整存储读数，包括波形，仅在请求时返回

• doctor - 离线、只读地诊断安装配置，不消耗配额

Related MCP server: google-health-mcp-server

数据类型

系统要求

• Python 3.13+（已在 CI 中针对 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 客户端。这需要七个控制台步骤，页面名称以 Google 2026 年 8 月为准。

Google 自己的设置页面会把您引导到别处 - 请按照下面的步骤操作。 其快速入门构建的是一个 Web 客户端，重定向 URI 为 https://www.google.com，这适用于 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 签发的刷新令牌会在授权同意后七天过期 - 所以一切正常，然后一周后同步停止，且没有任何线索指向此刻。受众群体页面可能显示"已正式发布"，但令牌服务器却不这么认为。有两个可靠的判断依据：品牌页面上的验证状态行，以及 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（不安全），并授予这些范围。

该流程会监听 localhost:8081 端口以接收回调，因此该端口必须可用。它会将令牌保存到 ~/.config/google-health-mcp/google_tokens.json，权限为 0600。访问令牌有效期为 1 小时，并会自动刷新。刷新令牌不会轮换，因此在一台有浏览器的机器上生成的令牌可以复制到无头机器上使用。

如果您在发布应用之前已授权，请在此后重新运行 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 在开始之前可能失败的两种方式。

离线且只读：它会报告哪些路径解析到了哪里、凭据文件格式是否正确、令牌是否为短期有效，以及缓存是否保持最新。

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
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
  --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（这两个工具不接受任何参数）外，所有查询工具都接受：

• start_date - YYYY-MM-DD、YYYY-MM 或 30d（相对日期）。默认值：最近 30 天。

• end_date - YYYY-MM-DD。默认值：今天。

• live - 如果为 true，则在读取缓存之前从 API 重新获取此时间窗口。刷新失败时会报告错误，而不是静默地从缓存中返回。

health_get_exercises 还接受 exercise_type，即对锻炼名称进行不区分大小写的子字符串匹配。health_get_ecg 还接受 include_waveform：一条轨迹包含数千个电压值，因此默认响应只包含分类、平均心率、时长和样本数。

health_sync

• data_types - all，或上面 CLI 用法 中列出的名称的逗号分隔子集（irn 表示心律不齐通知）。默认值：all。

• days - 首次同步的历史天数（默认值：30）。后续同步为增量同步。

• since / until - 无论缓存中有什么，都获取精确的时间窗口。

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 范围

在"数据访问"页面上勾选这些只读范围。所有范围都在 https://www.googleapis.com/auth/googlehealth. 下：

location.readonly 和 profile.readonly 是控制台提供的两个范围，本包有意不请求，因为这里没有任何功能会读取它们 - 第一个是锻炼期间记录的 GPS 轨迹。

请以控制台中的列表为准，而不是已发布的范围页面 - 有些只读范围既不出现在 Google 的文档中，也不出现在 API 自身的发现文档中，而发现文档则完全省略了 nutrition.readonly。要请求更少的范围，请在"数据访问"页面上少勾选，并在授权前编辑 config.py 中的 GOOGLE_SCOPES，这需要源码检出而不是 pip 或 uvx 安装。授权不会在刷新时获得新范围，因此之后要扩大列表，需要重新运行 auth。

配置

离线 / 仅缓存模式

默认情况下，服务器会按需同步，因此无需 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