内容
[](https://www.npmjs.com/package/google-health-mcp)
[](https://www.npmjs.com/package/google-health-mcp)
[](https://github.com/gorban-dev/google-health-mcp/actions/workflows/ci.yml)
[](https://nodejs.org)
[](LICENSE)
[](https://modelcontextprotocol.io)
**谷歌健康API**的MCP服务器：任何具有视觉功能的AI代理都可以将您的餐食（卡路里和宏量营养素）记录到谷歌健康中，并读取您的睡眠、活动和营养信息，以便一起分析。
典型流程：您拍摄食物照片并将其发送给您的代理（通过Telegram的Hermes Agent、OpenClaw、Claude Desktop、Cursor等）。代理根据照片估算菜肴和宏量营养素，调用`log_meal`，一分钟后，餐食信息就会出现在您的手机上的谷歌健康应用中，与您的睡眠和锻炼记录在一起。
反之亦然 - 询问代理 *"上个月怎么样？"*，它会调用`get_health_overview`，获取每日表格（步数、摄入/消耗卡路里、宏量营养素、水分、体重、静息心率、睡眠、锻炼），然后进行分析：蛋白质是否低于目标，晚餐时间是否与睡眠质量相关，体重趋势是否与卡路里赤字相符。说 *"我称重82.4"*，它就会通过`log_weight`记录到谷歌健康中。
为新的谷歌健康API（`health.googleapis.com/v4`）而构建 - 旧的Fitbit Web API将于2026年9月停止服务，本服务器**不依赖**它。
## 为什么您需要自己的谷歌云项目（请先阅读本节）
本服务器没有"登录即用"的按钮，这是故意的。谷歌将所有健康范围归类为**受限**：
- 未经验证的应用最多只能有**100名用户**，且此限制在云项目生命周期内不会重置。单个共享应用发布到npm后，该限制将在一天内被耗尽，并对所有人失效。
- 解除限制需要谷歌的信任与安全审查，以及**每年一次的CASA安全审计（$500–4500）**，并且需要应用内披露屏幕 - 对于本地stdio服务器来说，这是无法实现的，对于从未接触过您数据的开源工具来说也是不必要的。
- 谷歌的政策禁止跨多个云项目分散用户，这可能会导致开发者账户被封禁。
因此，每个用户都需要创建自己的**免费谷歌云项目**（约10分钟，一次性操作）。然后，您的数据将直接在您的机器和您的谷歌账户之间流动。本软件包的作者不运行任何服务器，也无法看到您的数据。
## 设置
要求：Node.js 20+，具有谷歌健康（Fitbit）数据的谷歌账户。
```bash
npx -y google-health-mcp setup
```
交互式向导将引导您完成以下每个步骤，打开正确的控制台页面，并以实时测试请求结束。向导将要求您：
1. **创建谷歌云项目** - [console.cloud.google.com/projectcreate](https://console.cloud.google.com/projectcreate)，任意名称。
2. **启用谷歌健康API** - APIs & Services → Library → 搜索"谷歌健康API" → 启用。
3. **配置OAuth同意屏幕** - 受众：外部；填写应用名称和两个电子邮件字段；跳过范围和测试用户。
4. **发布应用到生产环境。** ⚠️ 如果您将同意屏幕保留在*测试*状态，谷歌将在**7天**后过期您的刷新令牌，您将不得不每周重新授权。向导会检查此问题的症状，`doctor`会对问题进行诊断。
5. **创建OAuth客户端** - 凭证 → 创建凭证 → OAuth客户端ID → 类型**桌面应用**。将客户端ID和密钥粘贴到向导中。
6. **在浏览器中授权。** ⚠️ 谷歌将显示**"谷歌尚未验证此应用"。** 这是预期且正确的：应用是您两分钟前创建的自己的云项目；没有其他人可以为您验证它。点击**高级 → 继续访问（您的应用名称）（不安全）**并授予访问权限。
凭证存储在`~/.config/google-health-mcp/`（`config.json`、`tokens.json`，权限0600）。客户端密钥永远不会被记录。
其他命令：
```bash
npx -y google-health-mcp auth # 仅重新授权
npx -y google-health-mcp doctor # 诊断：令牌、权限、API测试调用、更新检查
npx -y google-health-mcp version # 打印已安装的版本
```
### 另外一件事：让营养信息在应用中可见
在谷歌健康应用中，营养指标（卡路里摄入、蛋白质、水分摄入...）最初处于**未跟踪**状态。打开营养并添加您关心的指标到跟踪列表中 - 否则，记录的食物将被存储但不会在仪表盘上显示。
## 连接到您的MCP客户端
配置在任何地方都是相同的 - 通过`npx`进行stdio：
```json
{
"mcpServers": {
"google-health": {
"command": "npx",
"args": ["-y", "google-health-mcp@latest"]
}
}
}
```
`@latest`使npx在每次客户端启动时重新解析最新的发布版本，因此更新会自动到达。如果没有它，npx将无限期提供缓存的副本。
**安装版本低于0.1.3？** 您的配置可能具有裸`google-health-mcp`规范，并且卡在旧缓存版本上。将其更改为`google-health-mcp@latest`，运行`rm -rf ~/.npm/_npx`一次（仅下载缓存 - `~/.config/google-health-mcp/`中的凭证不受影响），然后重启客户端。详细信息请参见[CHANGELOG.md](CHANGELOG.md)。
- **Claude Desktop**：`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）。
- **Cursor**：`~/.cursor/mcp.json`。
- **Hermes Agent**：将相同的块添加到Hermes配置的`mcp_servers`部分。
- **OpenClaw**：将块添加到`mcp.servers`中。
凭证也可以通过环境变量`GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET`注入，而不是`config.json`；时区可以通过`GOOGLE_HEALTH_TIMEZONE`注入（IANA名称，默认为系统时区）。
## 工具
写入：
| 工具 | 用途 |
|---|---|
| `log_meal` | 将一顿饭作为单独的项目记录（因此可以单独删除一个错误）。返回条目名称和餐食总数 |
| `log_food` | 记录单个食物项目 |
| `log_water` | 记录以毫升为单位的水分摄入量 |
| `log_weight` | 记录体重（千克），可选地记录体脂百分比 |
| `delete_food_log` | 按名称删除条目 - 修正路径，因为通过API创建的谷歌健康条目不可编辑 |
读取：
| 工具 | 用途 |
|---|---|
| `get_food_log` | 食物日记和每日营养总量 |
| `get_daily_summary` | 步数、消耗卡路里、活动分钟数 |
| `get_sleep` / `get_sleep_range` | 睡眠会话，包含阶段 |
| `get_activity_range` | 每天的活动记录 |
| `get_nutrition_range` | 每天的卡路里、宏量营养素和水分摄入记录 |
| `get_weight_range` | 每日平均体重和体脂百分比 |
| `get_heart_rate_range` | 每日静息心率和BPM最小/平均/最大值 |
| `get_workouts` | 锻炼会话，包含时长、卡路里、距离、平均心率 |
| `get_hrv` | 每日心率变异性 |
| `get_health_overview` | 所有上述内容的每日表格 - 分析和建议的入口点 |
| `get_profile` | 时区、测量单位 |
读取集存在，以便代理可以回答诸如"饮食如何影响睡眠"的问题 - 它可以关联数据，而不仅仅是写入。`get_health_overview`专门为此设计：一次调用可返回最多90天的综合数据。
体重、体脂和心率需要`health_metrics_and_measurements.readonly`范围。现在它包含在默认集中；如果您使用旧版授权，请运行`npx -y google-health-mcp@latest auth`一次以授予它。
## 精确度声明
根据照片估算营养信息是近似的：预计每餐**±120 kcal**的能量和**±8 g**的蛋白质误差，即使使用顶级视觉模型，个别微量营养素的误差也可能达到数十个百分点。此工具适合跟踪趋势。**不适合**临床需求 - 糖尿病管理、肾脏饮食或任何需要根据数字进行剂量计算的情况。
## 隐私
所有操作都在本地通过stdio运行。您的OAuth令牌永远不会离开您的机器；数据直接从您的机器发送到谷歌的API。作者不运营任何基础设施，不收集任何遥测数据，也无法看到您的数据。
## 开发
```bash
npm install
npm test # vitest
npm run lint # biome
npm run build
```
## 许可证
[MIT](LICENSE) © 2026 Sergey Gorban
