google-health-mcp 是一个 MCP 服务器，用于访问 Google Health API，覆盖心率、活动、睡眠、SpO2、HRV、ECG 和不规则心律通知等数据类型，并带有本地 SQLite 缓存与趋势分析功能。它面向 Claude Code 及其他 MCP 客户端设计，数据同步到用户自己的机器上的数据库，因此查询快速、可离线运行，而且不消耗 API 配额。
主要能力方面，该服务器提供本地 SQLite 缓存（同步一次即可即时查询）、增量同步（每次只抓取新增内容，并从上次中断处继续）、离线模式（无需凭据、无网络即可读取缓存）、趋势分析（按周、月或季度聚合，以及两个时段的对比）、ECG 支持（完整存储读数，包括波形，仅在需要时返回），以及 doctor 命令（离线只读诊断安装配置，不消耗配额）。
安装与使用要求：需要 Python 3.13+（已在 3.13 和 3.14 上测试，覆盖 Linux、macOS 和 Windows，CI 中运行）；需要一个带有健康数据的 Google 账号，以及一个用于授权的 Google Cloud 项目，无需结算账户。可以安装后运行，也可以用 uvx 免安装运行，例如将 google-health-mcp ... 命令替换为 uvx google-health-mcp ...。
配置流程需要用户自行创建 Google Cloud 项目并注册自己的 OAuth 客户端：创建项目、启用 Google Health API、完成 Google Auth Platform 的 Get started、在 Test users 下添加自己的 Google 账号、在 Data Access 中添加只读 scope、创建类型为 Desktop app 的 OAuth 客户端并下载其 JSON、最后发布应用。文档特别提醒，若应用发布状态为 Testing，Google 签发的刷新令牌会在同意后七天过期，可能导致同步在一周后停止；发布应用后需要重新运行 auth，因为发布不会延长已授予令牌的有效期。客户端 JSON 需原样放到服务器查找的位置。授权流程监听 localhost:8081 接收回调，令牌保存到 ~/.config/google-health-mcp/google_tokens.json（POSIX 上权限 0600）。
使用方式上，Query 工具在每天首次查询某数据类型时同步，然后读取缓存；工具支持 start_date（YYYY-MM-DD、YYYY-MM 或相对格式如 30d）、end_date、live 等参数，部分工具还支持 include_detail、include_waveform、include_stages、include_tcx 等开关以控制返回数据量。CLI 提供 sync 命令用于预填充缓存或拉取更早历史，支持 data_types、days、since/until 参数。doctor 提供离线只读诊断，--json 输出稳定标识 check 字段，退出码仅在存在 fail 级别的检查时为 1。
离线/纯缓存模式通过设置 GOOGLE_HEALTH_MCP_OFFLINE=1 启用：不需要凭据，不发起网络调用，自动同步关闭，live=True、health_get_devices 和 health_sync 会返回明确的离线模式提示，查询工具返回缓存数据并标记 "offline_mode": true。这种模式适用于多机共享同一缓存（一台主机用 cron 或 systemd 同步，其他机器只读），以及 CI 和隐私场景（无网络、无凭据查询）。
配额与隐私方面，Google 对每用户有请求配额，普通同步远低于限额：一天的更新只需少量请求，实测三年全数据类型回填约 250 次请求。同步中断时，该数据类型会记录为部分同步，下次运行从游标处继续。从缓存查询默认不消耗任何配额。健康数据保留在用户机器上，该服务器没有后端，不向任何地方发送数据，只用自己的凭据与 Google 的 API 通信。
此外，仓库提供 pre-commit 钩子，拒绝提交数据库文件、config/ 下的任何内容以及大文件。对于已有 JSON 格式健康数据的用户，可通过导入功能导入，期望的文件名包括 heart_rate.json、activity.json、exercises.json、sleep.json、weight.json、spo2.json、hrv.json 等七种类型，具体形状见 src/google_health_mcp/importer.py；其他类型通过同步获取。授权中缺少当前版本读取所需权限时，每个成功的工具响应都会附带说明，doctor 会在 check missing-scopes 下报告，sync 也会打印；这些数据类型会被跳过而非失败，sync 仍以 0 退出。项目采用 GPL-3.0-or-later 许可。