内容
# Whoop MCP 服务器
用于访问 Whoop 健身数据的模型上下文协议（MCP）服务器。将您的 WHOOP 生物识别数据集成到 Claude、LLM 和其他与 MCP 兼容的应用程序中。
[](https://railway.com/deploy/F1iI46?referralCode=I5P95N&utm_medium=integration&utm_source=template&utm_campaign=generic)
## 功能
- **综合概览** - 所有每日指标一目了然
- **睡眠分析** - 深入睡眠表现和质量
- **恢复指标** - HRV、RHR 和恢复贡献者
- **应激跟踪** - 每日应激，心率区和活动
- **健康寿命** - 生物年龄和老化速度指标
## 快速入门
1. **克隆仓库：**
```bash
git clone https://github.com/yourusername/whoop-mcp.git
cd whoop-mcp
```
2. **使用您的 WHOOP 凭证创建 `.env` 文件：**
```bash
echo "WHOOP_EMAIL=your-email@example.com" > .env
echo "WHOOP_PASSWORD=your-password" >> .env
echo "WHOOP_CLIENT_ID=your-whoop-client-id" >> .env
echo "PORT=3000" >> .env
```
或设置为环境变量：
```bash
export WHOOP_EMAIL='your-email@example.com'
export WHOOP_PASSWORD='your-password'
```
3. **安装依赖项：**
```bash
bun install
```
4. **启动服务器：**
```bash
bun run start
```
或使用热重载进行开发：
```bash
bun run dev
```
服务器默认在 `http://localhost:3000/mcp` 上运行。
## Docker 部署
1. **使用您的凭证创建 `.env` 文件：**
```bash
cp .env.example .env
# 使用您的实际凭证编辑 .env
```
2. **构建 Docker 镜像：**
```bash
docker build -t whoop-mcp .
```
3. **运行容器：**
```bash
docker run -d \
--name whoop-mcp \
whoop-mcp
```
`--env-file .env` 标志自动从您的 `.env` 文件加载所有环境变量。
4. **查看日志：**
```bash
docker logs -f whoop-mcp
```
5. **停止容器：**
```bash
docker stop whoop-mcp
```
Docker 镜像基于官方 Bun Alpine 镜像。容器包含健康检查以监控服务器状态。
## Smithery 部署
此服务器配置为与 [Smithery](https://smithery.ai/) 配合使用，Smithery 是一个用于部署 MCP 服务器的平台。在 Smithery 上部署时：
1. **通过查询参数配置**：Smithery 将您的凭证作为查询参数传递给 `/mcp` 端点（在 `smithery.yaml` 中定义）：
- `whoopEmail` - 您的 Whoop 账户电子邮件
- `whoopPassword` - 您的 Whoop 账户密码
- `mcpAuthToken` - 可选的身份验证令牌
2. **自动配置**：服务器在 Smithery 上运行时自动从查询参数中提取这些信息，因此您无需手动设置环境变量。
3. **部署按钮**：使用上面的 Railway 部署按钮进行快速部署，或遵循 [Smithery 文档](https://smithery.ai/docs) 获取其他部署选项。
存储库根目录中的 `smithery.yaml` 文件定义了 Smithery 用于安全收集您的凭证的配置模式。
## 配置
### 凭证配置
服务器支持两种提供凭证的方法：
1. **查询参数**（由 Smithery 使用）：将凭证作为查询参数传递给 `/mcp` 端点
- `whoopEmail` - 您的 Whoop 账户电子邮件
- `whoopPassword` - 您的 Whoop 账户密码
- `mcpAuthToken` - 可选的身份验证令牌
2. **环境变量**（用于本地/Docker 部署）：
| 变量 | 必需 | 默认值 | 描述 |
| ----------------- | ---- | ------ | --------------------------------------- |
| `WHOOP_EMAIL` | 是 | - | 您的 Whoop 账户电子邮件 |
| `WHOOP_PASSWORD` | 是 | - | 您的 Whoop 账户密码 |
| `WHOOP_CLIENT_ID` | 是 | - | 您的 Whoop API 客户端 ID |
| `MCP_AUTH_TOKEN` | 否 | - | MCP 请求的可选身份验证令牌 |
| `PORT` | 否 | 3000 | 服务器端口 |
服务器将首先检查查询参数，然后在未提供时回落到环境变量。
### 可选身份验证
为了保护您的 MCP 服务器免受未经授权的访问，您可以设置 `MCP_AUTH_TOKEN` 环境变量。设置后，所有对 `/mcp` 端点的请求都必须包含匹配的 Bearer 令牌：
```bash
export MCP_AUTH_TOKEN='your-secret-token-here'
```
或将其添加到您的 `.env` 文件中：
```bash
echo "MCP_AUTH_TOKEN=your-secret-token-here" >> .env
```
客户端必须在 Authorization 头中包含令牌：
```bash
curl -X POST http://localhost:3000/mcp \
-H "Authorization: Bearer your-secret-token-here" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","method":"tools/list","id":1}'
```
**注意：** 如果未设置 `MCP_AUTH_TOKEN`，服务器将接受所有请求（适用于本地开发）。
## 与 Claude Desktop 结合使用
将此配置添加到您的 Claude Desktop 配置文件中：
**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
### 无身份验证（本地开发）
```json
{
"mcpServers": {
"whoop": {
"command": "bun",
"args": ["run", "/absolute/path/to/whoop-mcp/index.ts"],
"env": {
"WHOOP_EMAIL": "your-email@example.com",
"WHOOP_PASSWORD": "your-password"
}
}
}
}
```
### 有身份验证（推荐）
```json
{
"mcpServers": {
"whoop": {
"command": "bun",
"args": ["run", "/absolute/path/to/whoop-mcp/index.ts"],
"env": {
"WHOOP_EMAIL": "your-email@example.com",
"WHOOP_PASSWORD": "your-password",
"MCP_AUTH_TOKEN": "your-secret-token-here"
}
}
}
}
```
将 `/absolute/path/to/whoop-mcp/` 替换为该目录的实际路径。
## 可用工具
服务器提供五个主要工具来访问您的 Whoop 数据：
### whoop_get_overview
检索特定日期的综合 Whoop 概览数据，单次 API 调用。
**参数：**
- `date`（可选）- YYYY-MM-DD 格式的日期。默认为今天。
**返回：**
- **周期信息**：周期 ID、天、日期显示、睡眠状态
- **实时指标**：恢复分数、每日应激、睡眠小时、卡路里消耗
- **仪表盘**：主页上的所有分数仪表盘
- **活动**：今天的活动，附带分数和时间
- **关键统计数据**：HRV、RHR、VO2 Max、呼吸率、30 天趋势的步数
- **日记**：日记完成状态
**示例用法：**
```
"您可以检查今天的 Whoop 数据吗？"
"2024-01-15 我的恢复分数是多少？”
“显示昨天的 Whoop 统计数据”
“我今天走了多少步？今天的活动是什么？”
```
### whoop_get_sleep
检索详细的睡眠分析和性能指标。
**参数：**
- `date`（可选）- YYYY-MM-DD 格式的日期。默认为今天。
**返回：**
- 睡眠性能分数
- 小时 vs 需要
- 睡眠一致性
- 睡眠效率
- 高睡眠压力百分比
- 个性化洞察和建议
**示例用法：**
```
"昨晚我睡得怎么样？”
“10 月 27 日的睡眠表现如何？”
“为什么今天我的睡眠分数很低？”
```
### whoop_get_recovery
检索综合的恢复深入分析，包括贡献者和趋势。
**参数：**
- `date`（可选）- YYYY-MM-DD 格式的日期。默认为今天。
**返回：**
- 恢复分数（0-100%）
- 恢复贡献者：
- 心率变异性（HRV）
- 静息心率（RHR）
- 呼吸率
- 睡眠表现
- 与 30 天基线相比的趋势指标
- 个性化教练洞察
**示例用法：**
```
"今天我的恢复分数是多少？”
“显示昨天的恢复分析”
“我的 HRV 与基线相比如何？”
```
### whoop_get_strain
检索综合的应激深入分析，包括贡献者、活动和趋势。
**参数：**
- `date`（可选）- YYYY-MM-DD 格式的日期。默认为今天。
**返回：**
- 应激分数，附带目标和最佳范围
- 应激贡献者：
- 心率区 1-3
- 心率区 4-5
- 力量活动时间
- 步数
- 今日活动，附带个别应激分数
- 与 30 天基线相比的趋势指标
- 个性化教练洞察
**示例用法：**
```
"今天我的应激分数是多少？”
“显示我的应激分析和活动”
“我在心率区 4-5 中花费了多少时间？”
“我是否达到了我的最佳应激目标？”
```
### whoop_get_healthspan
检索综合的健康寿命分析，包括 WHOOP 年龄（生物年龄）和老化速度指标。
**参数：**
- `date`（可选）- YYYY-MM-DD 格式的日期。默认为今天。
**返回：**
- WHOOP 年龄（生物年龄）
- 年龄状态（年轻、相同、比实际年龄大）
- 与实际年龄的年龄差异
- 老化速度（例如，0.5x = 比平均值老化得更慢）
- 与前一时期的比较
- 健康寿命测量的每周日期范围
**示例用法：**
```
"我的 WHOOP 年龄是多少？”
“显示我的生物年龄和健康寿命数据”
“我与平均值相比老化速度有多快？”
“我比实际年龄老化得更慢还是更快？”
```
## 工作原理
服务器自动处理身份验证：
1. 在首次请求时使用电子邮件/密码登录
2. 存储访问令牌（有效期为 24 小时）
3. 在令牌过期前自动重新身份验证
4. 在重新身份验证后重试失败的请求
## 安全
### 最佳实践
- **永远不要提交** 您的 `.env` 文件或分享您的 WHOOP 凭证
- 服务器仅在内存中存储 Whoop 身份验证令牌（它们在 24 小时后过期）
- **在将服务器暴露于网络或不受信任的客户端时，使用 `MCP_AUTH_TOKEN`**
- 为 `MCP_AUTH_TOKEN` 生成强大、随机的令牌（例如，使用 `openssl rand -hex 32`）
- 在生产环境或网络上运行时，**始终** 设置 `MCP_AUTH_TOKEN`
## 贡献
欢迎贡献！请随时提交拉取请求。
## 许可证
MIT - 有关详细信息，请参见 LICENSE 文件。
