AI导哈

Whoop健康数据服务器

一个提供全面访问Whoop API的模型上下文协议服务器，支持自动令牌刷新和长期认证，可查询周期、恢复、运动、睡眠等健康数据。

  • by leonhoulier
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 leonhoulier/whoop-mcp-server

使用说明

Whoop MCP服务器

模型上下文协议（MCP）服务器，提供对Whoop API的全面访问。该服务器允许语言模型和应用程序通过Whoop API自动刷新令牌和长期身份验证来查询周期、恢复、紧张、锻炼和睡眠数据。

注： 这个项目的灵感来自 ctvidic.特别感谢初步执行。

先决条件

Whoop开发者账户

要使用此服务器，您需要：

  1. Whoop开发者账户：注册地址： https://developer-dashboard.whoop.com
  2. 创建应用程序：创建帐户后，在开发人员仪表板中创建一个新应用程序
  3. 配置OAuth设置:
    • 设置重定向类型（例如。， https://your-domain.com/whoop/callback)
    • 复制您的客户端ID和客户端密码
    • 注：请求 offline 启用刷新令牌以进行长期身份验证的作用域

特性

  • 自动令牌刷新：令牌在到期前自动刷新（无需手动重新身份验证）
  • OAuth 2.0与PKCE：安全的身份验证流程
  • 离线范围支持：使用刷新令牌进行长期访问
  • 全面的API访问：所有Whoop v2 API终结点
  • 流式HTTP服务器：通过HTTP与MCP客户端兼容

可用工具

恢复数据

  • get_recovery_data：获取恢复数据，包括恢复评分、HRV、静息心率、SpO2和皮肤温度

周期数据

  • get_cycles_data：获取生理周期数据，包括压力、卡路里和心率指标
  • get_latest_cycle：获取最新的周期数据
  • get_average_strain：计算指定天数内的平均应变

睡眠数据

  • get_sleep_data：获取睡眠数据，包括睡眠阶段、表现百分比、质量评分、呼吸频率和效率
  • get_sleep_for_cycle：按周期ID获取特定周期的睡眠数据
  • get_latest_sleep：获取最新的睡眠数据

锻炼数据

  • get_workout_data：获取锻炼数据，包括运动、压力评分、心率区域、卡路里和GPS数据
  • get_workout_by_id：通过训练ID（UUID）获取特定训练
  • get_recent_workouts：获取过去7天的最新锻炼

身体尺寸

  • get_body_measurements：获取用户的身体测量数据，包括身高、体重和最大心率

认证

  • check_auth_status：检查身份验证状态并获取用户配置文件

安装

先决条件

  • Python 3.12+
  • Whoop开发人员帐户和OAuth凭据(把他们带到这儿来)
  • Nginx（用于生产部署）
  • PM2（用于过程管理，可选）

本地设置

  1. 克隆此存储库：
git clone https://github.com/leonhoulier/whoop-mcp-server.git
cd whoop-mcp-server
  1. 创建虚拟环境：
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. 安装依赖项：
pip install -r requirements.txt
  1. 配置环境变量：
cp config/.env.example config/.env
nano config/.env

添加您的Whoop OAuth凭据：

WHOOP_CLIENT_ID=your_client_id
WHOOP_CLIENT_SECRET=your_client_secret
WHOOP_REDIRECT_URI=https://your-domain.com/whoop/callback
  1. 通过Whoop进行身份验证：
./scripts/authenticate_whoop.sh

或者在启动服务器后访问重新身份验证端点：

https://your-domain.com/whoop/reauth

按照OAuth流程授权您的应用程序。令牌（包括刷新令牌）将自动保存，并带有过期跟踪功能。

部署

使用Nginx和PM2进行生产设置

此服务器被设计为在Nginx后面作为可流式传输的HTTP MCP服务器运行。

1.启动MCP服务器

默认情况下，服务器在端口8003上运行：

./start_whoop_mcp_http.sh

或手动：

cd /path/to/whoop-mcp-server
source venv/bin/activate
export MCP_HTTP_PORT=8003
python src/whoop_mcp_http_server.py

2.配置PM2（推荐）

安装PM2：

npm install -g pm2

将流程添加到PM2：

pm2 start start_whoop_mcp_http.sh --name whoop-mcp-http
pm2 save
pm2 startup

3.配置Nginx

添加到Nginx配置(/etc/nginx/sites-available/mcp.example.com):

server {
    listen 443 ssl http2;
    server_name mcp.example.com;

    ssl_certificate /etc/letsencrypt/live/mcp.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/mcp.example.com/privkey.pem;

    # Whoop MCP Server - Streamable HTTP
    location /whoop/mcp {
        proxy_pass http://localhost:8003/mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Accept "application/json, text/event-stream";
        proxy_buffering off;
    }

    # Whoop OAuth Callback (auto-exchanges tokens)
    location /whoop/callback {
        proxy_pass http://localhost:8003/callback;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Whoop Re-authentication Endpoint
    location /whoop/reauth {
        proxy_pass http://localhost:8003/reauth;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # Health Check
    location /whoop/health {
        proxy_pass http://localhost:8003/health;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

重新加载Nginx：

sudo nginx -t
sudo systemctl reload nginx

使用Cursor/Claude桌面

添加到您的Cursor或Claude Desktop MCP配置中：

{
  "mcpServers": {
    "whoop-mcp": {
      "url": "https://your-domain.com/whoop/mcp"
    }
  }
}

认证

Whoop MCP使用OAuth 2.0和PKC进行安全身份验证。服务器包括：

  • 自动令牌刷新：访问令牌在到期前自动刷新（到期后5分钟内）
  • 刷新令牌支持：与的长期身份验证 offline 范围
  • 主动刷新：令牌会自动刷新，消除了手动重新身份验证
  • 重新身份验证端点：轻松重新认证 /whoop/reauth
  • 自动令牌交换：OAuth回调自动为令牌交换授权码

获取OAuth凭据

  1. 在以下网址创建Whoop开发者帐户 https://developer-dashboard.whoop.com
  2. 在开发人员仪表板中注册新应用程序
  3. 配置重定向URI: https://your-domain.com/whoop/callback
  4. 将客户端ID和客户端密码复制到您的 .env 文件
  5. 重要：确保 offline 请求作用域接收刷新令牌

环境变量

所需的环境变量：

  • WHOOP_CLIENT_ID：您的Whoop OAuth客户端ID
  • WHOOP_CLIENT_SECRET：您的Whoop OAuth客户端密码
  • WHOOP_REDIRECT_URI：您的OAuth回调URL
  • MCP_HTTP_PORT：MCP HTTP服务器的端口（默认值：8003）
  • WHOOP_DOCS_PORT：文档服务器端口（默认值：8005）

项目结构

whoop-mcp-server/
├── src/
│   ├── whoop_mcp_server.py           # Core MCP server implementation
│   ├── whoop_mcp_http_server.py      # Streamable HTTP server
│   ├── whoop_mcp_sse_server.py       # Legacy SSE server
│   └── ...
├── config/
│   ├── .env.example                  # Environment variables template
│   └── tokens.json                   # Stored OAuth tokens (gitignored)
├── scripts/
│   ├── authenticate_whoop.sh         # OAuth authentication script
│   └── authenticate_whoop.py         # OAuth helper Python script
├── storage/                          # OAuth storage
├── whoop_docs_server.py              # Documentation server
├── start_whoop_mcp_http.sh           # MCP HTTP startup script
├── start_whoop_docs.sh               # Docs server startup script
├── requirements.txt                  # Python dependencies
└── README.md                         # This file

API 参考

服务器使用Whoop API v2。看 Whoop开发者文档 API完整规范。

故障排除

令牌到期

配置刷新令牌后，您应该 不 需要手动重新验证。但是，如果您收到身份验证错误：

  1. 访问 https://your-domain.com/whoop/reauth
  2. 使用Whoop重新授权
  3. 新令牌（包括刷新令牌）将自动保存

服务器未启动

检查PM2日志：

pm2 logs whoop-mcp-http

验证端口是否可用：

lsof -i :8003

404错误

确保Nginx配置与您的实际端口和端点匹配。服务器公开：

  • /mcp -主MCP端点
  • /health -健康检查
  • /reauth -重新身份验证
  • /callback -OAuth回调（自动交换令牌）

无刷新令牌

如果您没有收到刷新令牌：

  1. 确保 offline 作用域包含在OAuth请求中
  2. 在Whoop开发人员仪表板中验证您的应用程序是否已批准离线访问
  3. 检查服务器日志以获取作用域信息

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

作者

莱昂·霍利尔- Leonhoulier.com

致谢

这个项目的灵感来自 ctvidic.使用模型上下文协议SDK和Whoop API构建。

相关 MCP