google-health-fitbit-mcp

<h1 align="center">谷歌健康 Fitbit 连接器</h1> <div align="center"> <img src="https://raw.githubusercontent.com/BerkKilicoglu/google-health-fitbit-mcp/main/assets/banner.png" alt="谷歌健康 Fitbit 连接器 — 为 AI 代理提供谷歌健康 API 连接器" width="85%" /> </div> <h3 align="center"> 查询您自己的谷歌健康 API 数据 — Fitbit、Pixel Watch 和已连接的合作伙伴来源 — 通过本地 OAuth。<strong>测试版</strong>。<br> 所有操作都在您的机器上运行 — <strong>您的凭证从未离开您的设备</strong>。 </h3> <p align="center"> <a href="https://www.npmjs.com/package/google-health-fitbit-mcp"><img src="https://img.shields.io/npm/v/google-health-fitbit-mcp?style=for-the-badge&labelColor=0F172A&color=10B981&logo=npm&logoColor=white" alt="npm 版本" /></a> <a href="https://www.npmjs.com/package/google-health-fitbit-mcp"><img src="https://img.shields.io/npm/dm/google-health-fitbit-mcp?style=for-the-badge&labelColor=0F172A&color=0EA5A3&logo=npm&logoColor=white" alt="npm 下载量" /></a> <a href="https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/LICENSE-MIT-22C55E?style=for-the-badge&labelColor=0F172A" alt="MIT 许可证" /></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/BUILT_FOR-MCP-7C3AED?style=for-the-badge&labelColor=0F172A" alt="为 MCP 构建" /></a> <a href="https://github.com/BerkKilicoglu/google-health-fitbit-mcp/stargazers"><img src="https://img.shields.io/github/stars/BerkKilicoglu/google-health-fitbit-mcp?style=for-the-badge&labelColor=0F172A&color=FBBF24&logo=github" alt="GitHub 星标" /></a> </p> --- **一个在本地运行的 MCP 服务器，为您的 AI 代理提供您自己的谷歌健康 API 数据 — 来自 Fitbit 追踪器、Pixel Watch 和支持的合作伙伴来源 — 通过 OAuth。** - **一键安装** — `npx -y google-health-fitbit-mcp setup` - **在以下平台运行**：Claude Desktop、Claude Code、Cursor、Windsurf、Hermes、OpenClaw — 请参阅 [客户端示例](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/tree/main/examples)。 - **在您的机器上** — OAuth 令牌存储在本地，权限为 `0600`，并且从未被任何工具返回（[隐私](#隐私和离线运行)）. - **默认只读** — 每个附带的 数据工具都是只读的。写入是需要明确用户许可的，且默认为干预运行。 > **测试版状态：** 谷歌健康 API 对开发者开放，但其表面仍在变化。由于谷歌的发布说明不断列出范围和数据类型更改，因此该连接器仍处于测试版，并引导测试者进行安全的只读验证，然后再进行任何生产使用。 > 独立、社区建设的连接器 — 与谷歌、Fitbit 或 Alphabet 无关联、无背书或支持。不是医疗设备或医疗建议；仅将数据视为趋势背景。 ## ⚡ 快速连接 > 先决条件：一个谷歌云 OAuth 客户端（类型：桌面），启用了[谷歌健康 API](https://console.cloud.google.com/apis/library/health.googleapis.com)，并且注册了重定向 `http://127.0.0.1:3000/callback` — 详见[安装](#安装)。 **步骤 1 — 安装和授权（一次）：** ```bash npx -y google-health-fitbit-mcp setup # 引导：谷歌云 OAuth 客户端 + 作用域 npx -y google-health-fitbit-mcp auth # 浏览器 OAuth — 令牌保留在您的机器上 npx -y google-health-fitbit-mcp checkup # ✓ 验证所有内容已准备就绪 ``` <details> <summary><b>🔑 首次使用？获取您的谷歌客户端 ID 和密钥（约 2 分钟）</b></summary> `setup` 会要求提供 **客户端 ID** 和 **客户端密钥**。您可以在谷歌云中免费创建这些： 1. **新建项目** — 打开 [console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate)，命名它（例如 `health-mcp`），点击 **创建**，然后选择它。 2. **启用 API** — 打开 [谷歌健康 API](https://console.cloud.google.com/apis/library/health.googleapis.com) 页面并点击 **启用**。 3. **同意屏幕** — 进入 [OAuth 同意屏幕](https://console.cloud.google.com/apis/credentials/consent)，选择 **外部**，并填写必填的应用名称/电子邮件字段。在 **测试用户** 下，**添加您自己的谷歌账户** — 跳过此步骤，登录将失败，出现 `403: access_denied`。 4. **创建客户端** — 进入 [凭证](https://console.cloud.google.com/apis/credentials) → **+ 创建凭证 → OAuth 客户端 ID** → **应用类型：桌面应用** → **创建**。 5. **复制** **客户端 ID**（以 `…apps.googleusercontent.com` 结尾）和 **客户端密钥**，然后在 `setup` 提示时粘贴每个。 > **重定向 URI:** 桌面应用客户端自动允许 `http://127.0.0.1:3000/callback` 回环 — 您无需在任何地方注册它。只需按 **Enter** 接受默认值即可。 </details> **步骤 2 — 连接您的应用：** <details> <summary><b>Claude 代码</b></summary> ```bash claude mcp add google-health -- npx -y google-health-fitbit-mcp ``` </details> <details> <summary><b>Claude 桌面版</b></summary> 设置 → 开发者 → 编辑配置，然后在 `claude_desktop_config.json` 中添加： ```json { "mcpServers": { "google_health": { "command": "npx", "args": ["-y", "google-health-fitbit-mcp"] } } } ``` 重启 Claude 桌面版 — 工具将出现在 🔌 连接器菜单下。 </details> <details> <summary><b>光标</b></summary> 将相同的 `mcpServers` 块添加到 `.cursor/mcp.json`（每个项目）或 `~/.cursor/mcp.json`（全局），或使用设置 → MCP → 添加新服务器。 ```json { "mcpServers": { "google_health": { "command": "npx", "args": ["-y", "google-health-fitbit-mcp"] } } } ``` </details> <details> <summary><b>风云</b></summary> 将相同的 `mcpServers` 块添加到 `~/.codeium/windsurf/mcp_config.json`。 </details> <details> <summary><b>赫尔墨斯</b></summary> ```bash npx -y google-health-fitbit-mcp setup --client hermes # 为您编写赫尔墨斯配置 ``` 然后使用 `/reload-mcp` 或 `hermes mcp test google_health` 重载。 </details> **步骤 3 — 测试。** 向您的代理询问： ```text 运行 google_health_connection_status 并告诉我是否已连接。 ``` ## 为什么存在 谷歌健康 API 是 Fitbit Web API 的继任者：新的 OAuth、新的基准 URL（`https://health.googleapis.com`）、精简的端点架构、标准化的 kebab-case 数据类型、协调的跨源流和每日/物理时间汇总。 它为代理提供了一条干净的路径来探索 API、验证设置、本地登录和提取数据 — 无需将令牌粘贴到提示或代理配置中。 ## 试用您的代理 围绕此连接器真正附带的工具构建的三个良好起始提示： ```text 使用 google_health_connection_status 检查我的设置，然后调用 google_health_data_inventory 并告诉我我已授予哪些 谷歌健康域和作用域。 ``` ```text 拉取今天的 google_health_daily_summary，然后是 google_health_weekly_summary。 保持观测数据与任何建议分开，并保持非医疗。 ``` ```text 使用 google_health_list_paired_devices 列出我的配对设备，并告诉我 哪个设备正在生成我的睡眠和心率数据。 ``` ## 工具 29 个工具，除两个明确限定的本地配置文件/身份验证操作外，均只读。 ### 从这里开始 | 工具 | 它做什么 | |---|---| | `google_health_connection_status` | 本地配置、令牌、作用域和 MCP 客户端准备情况 — 无谷歌调用 | | `google_health_quickstart` | 个性化的 3 步设置向导，根据您的当前状态进行调整 | | `google_health_data_inventory` | 支持的域、作用域、数据类型命名和推荐的代理流程 | | `google_health_list_data_types` | 39 个 kebab-case 数据类型 slug，带有单位、作用域和支持的动词 | | `google_health_demo` | 代理在进行实际调用之前看到的现实综合有效载荷 | ### 数据读取（谷歌健康 API） | 工具 | 端点 | |---|---| | `google_health_get_identity` | `/v4/users/me/identity` — 谷歌健康 + 旧版 Fitbit 身份映射 | | `google_health_get_profile` | `/v4/users/me/profile` | | `google_health_get_settings` | `/v4/users/me/settings` — 单位、时区 | | `google_health_list_paired_devices` | `/v4/users/me/pairedDevices` — 您的 Fitbit 追踪器和 Pixel Watch，以及哪个设备生成哪些数据 | | `google_health_get_irn_profile` | `/v4/users/me/irnProfile` — 不规则心律（心房颤动）通知参与状态 | | `google_health_list_data_points` | `/v4/.../dataPoints` — 任意数据类型的日内详细信息 | | `google_health_get_data_point` | `/v4/.../dataPoints/{id}` — 特定的睡眠会话、锻炼或测量 | | `google_health_reconcile_data_points` | `/v4/.../dataPoints:reconcile` — 来自源的干净流（所有源、google-wearables、google-sources） | | `google_health_daily_rollup` | `/v4/.../dataPoints:dailyRollUp` — 民用日聚合 | | `google_health_rollup` | `/v4/.../dataPoints:rollUp` — 物理时间窗口聚合 | ### 摘要和健康背景 | 工具 | 它做什么 | |---|---| | `google_health_daily_summary` | 一天的步数、距离、卡路里、活跃区分钟数、睡眠、静息心率、心率变异性和体重，带有数据质量标志 | | `google_health_weekly_summary` | 每周记分卡，可选的先前窗口比较、负载分类和瓶颈 | | `google_health_wellness_context` | 用于推荐引擎的规范化活动/睡眠上下文 | ### 身份验证、诊断和元数据 `google_health_get_auth_url` · `google_health_exchange_code`（需要明确的用户意图）· `google_health_revoke_access`（需要明确的用户意图 + 破坏性：断开谷歌健康）· `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`。 ## 数据类型 来自官方谷歌健康表格的 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`。 命名规则代理需要： - **端点** 使用 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` 获取具有单位、作用域和每个类型支持的动词（列表/协调/滚动）的完整目录。 ## 隐私和离线运行 - 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` 为测试版测试者打印一份匿名的设置反馈包（[指南](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/docs/setup-feedback.md)）。 - `coverage --live --json` 仅打印编辑过的数据类型状态和点数桶 — 从不原始的谷歌健康有效载荷（[指南](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/docs/data-coverage.md)）。 ## 安装 设置一个谷歌云 OAuth 客户端（类型：桌面），启用[谷歌健康 API](https://console.cloud.google.com/apis/library/health.googleapis.com)，并注册本地重定向： ```text http://127.0.0.1:3000/callback ``` 然后运行： ```bash 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 同意易于理解 — 仅请求您的用例所需的内容： | 预设 | 授予 | |---|---| | `basic` | 配置文件 + 设置 | | `activity` | 基础 + 活动/健身 + 健康指标 | | `sleep` | 基础 + 睡眠 | | `heart` | 基础 + 健康指标 + **ECG** + **不规则心律通知** | | `full` | 所有推荐的只读作用域（默认） | | `nutrition-write` | 选择加入营养写入作用域 — 唯一具有写入能力的预设；目前尚无写入工具。 | 高级用户可以使用 `--scopes` 传递显式空格/逗号分隔的作用域列表。 ### 如果设置卡住 ```bash npx -y google-health-fitbit-mcp checkup --fix # 修复本地配置/令牌权限（支持chmod 600） npx -y google-health-fitbit-mcp checkup --live # 访问只读身份/配置文件/设置端点以确认API响应 npx -y google-health-fitbit-mcp coverage --live --json # 编辑过的数据类型覆盖报告 npx -y google-health-fitbit-mcp support # 可分享的支持包，剥离令牌/密钥/测量值 npx -y google-health-fitbit-mcp support --feedback --json # 匿名设置反馈包 ``` ### MCP 客户端配置 Claude 桌面版/光标/风云（参见[示例](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/tree/main/examples)）： ```json { "mcpServers": { "google_health": { "command": "npx", "args": ["-y", "google-health-fitbit-mcp"] } } } ``` ### 赫尔墨斯 ```bash 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 传输： ```bash npx -y google-health-fitbit-mcp --http # 服务于 http://127.0.0.1:3000/mcp (+ /health) ``` ## 配置 | 环境变量 | 用途 | 默认值 | |---|---|---| | `GOOGLE_HEALTH_CLIENT_ID` | 谷歌云 OAuth 客户端 ID | — （或本地配置） | | `GOOGLE_HEALTH_CLIENT_SECRET` | OAuth 客户端密钥（优先于本地配置使用 MCP 客户端配置） | — （或本地配置） | | `GOOGLE_HEALTH_REDIRECT_URI` | 已注册的重定向 URI | — （或本地配置） | | `GOOGLE_HEALTH_TOKEN_PATH` | 令牌文件位置 | `~/.google-health-mcp/tokens.json` | | `GOOGLE_HEALTH_PRIVACY_MODE` | `summary` \| `structured` \| `raw` | `structured` | | `GOOGLE_HEALTH_CACHE` | 可选的 SQLite 响应缓存（`true`/`sqlite`） | 禁用 | | `GOOGLE_HEALTH_CACHE_PATH` | SQLite 缓存位置 | `~/.google-health-mcp/cache.sqlite` | | `GOOGLE_HEALTH_NO_CACHE` | 绕过内存 HTTP 缓存（60 秒 TTL，仅限 GET） | 未设置 | | `GOOGLE_HEALTH_MCP_TRANSPORT` | `stdio` \| `http` | `stdio` | | `GOOGLE_HEALTH_MCP_HOST` / `GOOGLE_HEALTH_MCP_PORT` | HTTP 传输绑定地址 | `127.0.0.1` / `3000` | 可靠性内置：每个谷歌调用都经过重试中间件（指数退避 + 抖动，遵守 `Retry-After`，重试 408/429/5xx）和 60 秒的 GET 响应缓存。多日摘要限制请求并发以保持在速率限制之下。 ## CLI 命令 所有命令都通过 `npx -y google-health-fitbit-mcp <command>` 运行（已安装的二进制文件：`google-health-fitbit-mcp-server`）。 | 命令 | 它做什么 | 关键标志 | |---|---|---| | *(无)* | 在 stdio 上启动 MCP 服务器 | `--http` — 本地 Streamable-HTTP 在 `127.0.0.1:3000/mcp` | | `setup` | 引导设置：写入本地配置 + MCP 客户端配置 | `--scope-preset <basic\|activity\|sleep\|heart\|full\|nutrition-write>` · `--scopes "<url …>"` · `--client <generic\|claude\|cursor\|windsurf\|hermes\|openclaw>` · `--no-auth` · `--json` | | `auth` | 带有本地回调的浏览器 OAuth；保存具有 `0600` 权限的令牌 | `--no-open` — 打印 auth URL 而不是打开浏览器 | | `checkup` | 设置诊断，带有 ✓/✗ 检查和下一步 | `--json` · `--client <name>` · `--fix` — 修复文件权限 · `--live` — 证明 API 可达性 · `--live-write` — 写入路径的干预运行，永不 POST | | `coverage` | 跨列表/协调/汇总的数据类型覆盖报告 | `--json` · `--live` — 针对您真实账户的只读检查 | | `support` | 为 GitHub 问题提供的已编辑支持包 | `--json` · `--feedback` — 匿名设置反馈包 | | `onboarding` | 作为 JSON 的共享健康入职流程 | `--pt-BR` | | `version` / `help` | 打印版本/完整用法 | | ## 测试版测试者 现在，最有价值的贡献是使用真实的 Fitbit、Pixel Watch、Android 和谷歌健康 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 令牌、客户端密钥、本地路径和个人健康测量值**排除**在公共问题之外。 ## 开发 ```bash 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 UX 检查和元数据验证。有关指南，请参阅 [CONTRIBUTING.md](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/CONTRIBUTING.md)，有关安全策略，请参阅 [SECURITY.md](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/SECURITY.md)。 ## 链接 - 谷歌健康 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 → 谷歌健康）：https://developers.google.com/health/migration ## 联系和支持 - 🐛 **错误报告/功能请求** — [GitHub 问题](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/issues) - 📨 **klcogluberk@gmail.com** — 一般性问题和集成帮助 ## 许可证 MIT — 参见 [LICENSE](https://github.com/BerkKilicoglu/google-health-fitbit-mcp/blob/main/LICENSE)。