google-health-fitbit-mcp

Google Health Fitbit MCP

通过本地 OAuth 查询您自己的 Google Health API 数据 — Fitbit、Pixel Watch 和已连接的合作伙伴数据源 —。Beta。
所有操作都在您自己的设备上运行 — 您的凭据绝不会离开您的设备。

一个在本地运行的 MCP 服务，通过 OAuth 将您自己的 Google Health API 数据交给 AI Agent——数据来自 Fitbit 追踪器、Pixel Watch 和受支持的合作伙伴数据源。

• 一条命令即可安装 — npx -y google-health-fitbit-mcp setup
• 可在以下客户端中运行 Claude Desktop · Claude Code · Cursor · Windsurf · Hermes · OpenClaw — 请参阅客户端示例。
• 在您的设备上运行 — OAuth 令牌以 0600 权限保存在本地，任何工具都不会返回这些令牌（隐私）。
• 默认只读 — 所有随附的数据工具都只执行读取操作。写入功能采用受控、选择加入、先试运行的设计，目前未启用。

Beta 状态： Google Health API 已向开发者开放，但其功能范围仍在变化。由于 Google 的发布说明在上线后仍持续列出权限范围和数据类型的变更，此连接器仍处于 Beta 阶段，并建议测试者在用于生产环境前先安全地验证只读功能。

这是一个独立的社区构建连接器——与 Google、Fitbit 或 Alphabet 无隶属关系，也未获得其认可或支持。它不是医疗器械，也不提供医疗建议；请仅将这些数据作为趋势参考。

⚡ 快速连接

前提条件：一个已启用 Google Health API 并注册了重定向地址 http://127.0.0.1:3000/callback 的 Google Cloud OAuth 客户端（类型：Desktop）——详情请见安装。

步骤 1 — 安装并授权（仅需一次）：

npx -y google-health-fitbit-mcp setup     # guided: Google Cloud OAuth client + scopes
npx -y google-health-fitbit-mcp auth      # browser OAuth — tokens stay on your machine
npx -y google-health-fitbit-mcp checkup   # ✓ verifies everything is ready

步骤 2 — 连接应用：

claude mcp add google-health -- npx -y google-health-fitbit-mcp

{
  "mcpServers": {
    "google_health": {
      "command": "npx",
      "args": ["-y", "google-health-fitbit-mcp"]
    }
  }
}

{
  "mcpServers": {
    "google_health": {
      "command": "npx",
      "args": ["-y", "google-health-fitbit-mcp"]
    }
  }
}

npx -y google-health-fitbit-mcp setup --client hermes   # writes the Hermes config for you

步骤 3 — 测试。 向你的 Agent 提问：

Run google_health_connection_status and tell me if I'm connected.

为什么要开发这个项目

Google Health API 是 Fitbit Web API 的后继者：采用全新的 OAuth 和基础 URL（https://health.googleapis.com），端点架构更精简，数据类型统一为 kebab-case，跨来源数据流经过协调，并支持按日 / 实际时间汇总。

它为 Agent 提供了一条清晰的路径来探索 API、验证配置、本地登录并提取数据 — 无需将令牌粘贴到提示词或 Agent 配置中。

与你的 Agent 一起试用

以下是三个不错的入门提示词，均围绕此连接器实际提供的工具设计：

Check my setup with google_health_connection_status, then call
google_health_data_inventory and tell me which Google Health
domains and scopes I've granted.

Pull today's google_health_daily_summary, then google_health_weekly_summary.
Keep observed data separate from any suggestions, and stay non-medical.

List my paired devices with google_health_list_paired_devices and tell me
which device is producing my sleep and heart-rate data.

工具

共 29 个工具，除下文明确说明的两个受限本地个人资料 / 身份验证操作外，均为只读。

从这里开始

数据读取（Google Health API）

摘要和健康情境

身份验证、诊断和元数据

google_health_get_auth_url · google_health_exchange_code（受限：需要明确的用户意图）· google_health_revoke_access（受限且具有破坏性：断开 Google Health）· google_health_privacy_audit · google_health_cache_status · google_health_data_type_coverage · google_health_capabilities · google_health_agent_manifest · google_health_onboarding · google_health_profile_get · google_health_profile_update（仅修改本地文件，需要 explicit_user_intent=true）

资源和提示词

MCP 资源：google-health://agent-manifest、google-health://capabilities、google-health://inventory、google-health://latest/steps、google-health://profile、google-health://summary/daily、google-health://summary/weekly。

MCP 提示词：google_health_daily_checkin、google_health_weekly_review、google_health_data_type_investigation。

数据类型

官方 Google Health 表中的 39 种数据类型，包括 steps、sleep、heart-rate、heart-rate-variability、daily-resting-heart-rate、active-zone-minutes、distance、total-calories、weight、body-fat、blood-glucose、oxygen-saturation、vo2-max、electrocardiogram、irregular-rhythm-notification、exercise、floors、swim-lengths-data、nutrition-log 和 hydration-log。

Agent 需要了解的命名规则：

• 端点使用 kebab-case 数据类型：steps、daily-resting-heart-rate。
• 筛选条件使用 snake_case 字段路径：sleep.interval.civil_start_time、heart_rate.sample_time.physical_time。
• 来源系列：all-sources、google-wearables、google-sources。

调用 google_health_list_data_types，查看包含单位、授权范围以及各类型支持的操作（list/reconcile/rollup）的完整目录。

隐私与离线运行的部分

• OAuth 令牌存储在磁盘上的 ~/.google-health-mcp/tokens.json 中，并限制为 0600 权限。
• 客户端密钥存储在 ~/.google-health-mcp/config.json 中，或通过 GOOGLE_HEALTH_* 环境变量提供。
• 工具绝不会返回访问令牌、刷新令牌或客户端密钥；错误输出也会进行脱敏。
• 默认隐私模式为 GOOGLE_HEALTH_PRIVACY_MODE=structured；summary 会进一步移除标识符，而 raw 则是调试时明确选择启用的模式。
• GPS/路线数据被视为敏感信息，除非明确请求，否则会进行脱敏。
• support 会输出可复制粘贴到 GitHub 问题中的支持信息包——始终经过脱敏，绝不包含令牌、密钥、本地路径或健康测量数据。
• support --feedback --json 会为 beta 测试人员输出匿名的设置反馈信息包（指南）。
• coverage --live --json 只会输出经过脱敏的数据类型状态和数据点数量区间，不会输出原始 Google Health 负载（指南）。

安装

设置 Google Cloud OAuth 客户端（类型：Desktop），启用 Google Health API，并注册本地重定向地址：

http://127.0.0.1:3000/callback

然后运行：

npx -y google-health-fitbit-mcp setup --scope-preset full
npx -y google-health-fitbit-mcp auth
npx -y google-health-fitbit-mcp checkup

范围预设

预设让 OAuth 同意请求一目了然——只请求用例所需的权限：

高级用户可以通过 --scopes 传入以空格或逗号分隔的明确权限范围列表。

如果设置遇到问题

npx -y google-health-fitbit-mcp checkup --fix        # repairs local config/token permissions (chmod 600 where supported)
npx -y google-health-fitbit-mcp checkup --live       # hits read-only identity/profile/settings endpoints to confirm the API responds
npx -y google-health-fitbit-mcp coverage --live --json  # redacted read-only data-type coverage report
npx -y google-health-fitbit-mcp support             # shareable support bundle, stripped of tokens/secrets/measurements
npx -y google-health-fitbit-mcp support --feedback --json  # anonymous setup feedback bundle

保持连接

访问令牌会在后台静默刷新。真正会过期的是其背后的刷新令牌——当同意屏幕的发布状态为 Testing 时，Google 会在 7 天后撤销该令牌，下一次调用将返回 invalid_grant。重试无法解决问题：授权已失效，只有重新授权才能恢复。

因此，服务会代你完成授权。首次调用遇到已撤销的授权时，它会在浏览器中打开 Google 的同意屏幕；批准后，原始请求会自动完成——无需运行命令，也无需排查问题。如果所用时间超过 GOOGLE_HEALTH_REAUTH_WAIT_MS（默认为 45 秒），调用会改为返回 URL，且监听器会继续运行，因此批准操作仍然有效，下一次请求也会正常执行。

此功能仅适用于本地 stdio 传输方式，此时浏览器和服务运行在同一台机器上。使用 HTTP 传输时，服务可能位于远程，而且默认端口会与环回重定向端口冲突，因此调用会失败并明确提示你运行 auth。设置 GOOGLE_HEALTH_AUTO_REAUTH=0 可始终自行处理重新授权；在无头主机上设置 GOOGLE_HEALTH_AUTH_NO_BROWSER=1 可仅获取 URL，而不启动浏览器。

MCP 客户端配置

Claude Desktop / Cursor / Windsurf（参见 examples/）：

{
  "mcpServers": {
    "google_health": {
      "command": "npx",
      "args": ["-y", "google-health-fitbit-mcp"]
    }
  }
}

Hermes

npx -y google-health-fitbit-mcp setup --client hermes --no-auth
npx -y google-health-fitbit-mcp auth
npx -y google-health-fitbit-mcp checkup --client hermes

配置更改后，运行 /reload-mcp 或 hermes mcp test google_health 即可——只为读取数据，无需重启网关。

HTTP 传输（可选）

默认传输方式为 stdio。需要此方式的客户端可以使用本地 Streamable-HTTP 传输：

npx -y google-health-fitbit-mcp --http   # serves http://127.0.0.1:3000/mcp (+ /health)

配置

内置可靠性保障：每次 Google 调用都会经过重试中间件（指数退避 + 抖动、遵循 Retry-After，并重试 408/429/5xx），且使用仅限 GET、有效期为 60 秒的响应缓存。多日汇总会限制请求并发量，以避免触及速率限制。

CLI 命令

所有命令均通过 npx -y google-health-fitbit-mcp <command> 运行（已安装的二进制文件：google-health-fitbit-mcp-server）。

征集 Beta 测试者

目前最有价值的贡献，是基于真实 Fitbit、Pixel Watch、Android 和 Google Health API 账户提供实际设置反馈。

如果你有真实账户可用于测试：

• 运行 npx -y google-health-fitbit-mcp checkup，并告知我们 OAuth 流程是否清晰易懂。
• 运行 npx -y google-health-fitbit-mcp support --feedback --json，并将匿名信息包发布到 GitHub 问题中。
• 完成 OAuth 后，运行 npx -y google-health-fitbit-mcp coverage --live --json，检查后发布脱敏后的覆盖率报告。
• 在 MCP 客户端中试用 google_health_connection_status、google_health_data_inventory 和 google_health_daily_summary。
• 如果遇到缺少数据类型、设置步骤不清晰、特定客户端使用不便或隐私问题，请提交问题。
• 请勿在公开问题中包含 OAuth 令牌、客户端密钥、本地路径和个人健康测量数据。

开发

git clone https://github.com/BerkKilicoglu/google-health-fitbit-mcp.git
cd google-health-fitbit-mcp
npm install
npm test

npm test 会运行类型检查、构建、MCP 冒烟测试（stdio + HTTP）、摘要测试样例、隐私/缓存/重试测试套件、CLI 体验检查和元数据验证。请参阅 CONTRIBUTING.md 了解指南，并参阅 SECURITY.md 了解安全政策。

链接

• Google Health API：https://developers.google.com/health
• 发行说明：https://developers.google.com/health/release-notes
• REST 参考：https://developers.google.com/health/reference/rest
• 权限范围：https://developers.google.com/health/scopes
• 数据类型：https://developers.google.com/health/data-types
• 迁移指南（Fitbit → Google Health）：https://developers.google.com/health/migration

联系与支持

• 🐛 错误报告 / 功能请求 — GitHub Issues
• 📨 [email protected] — 一般问题和集成协助

许可证

MIT — 请参阅 LICENSE。