🏃 WHOOP MCP 服务器

通过模型上下文协议 (MCP) 将您的 WHOOP 健身数据连接到 Claude Desktop

通过 Claude Desktop 中的自然语言查询，将您的 WHOOP 健身数据转化为可操作的见解。询问有关您的锻炼、恢复、睡眠模式等问题——同时确保您的数据安全和私密。

🚀 新功能：尝试 Smithery 托管版本 以实现零配置部署！

✨ 功能

🔐 安全 OAuth 集成 - 通过加密的本地存储安全连接 WHOOP 账户 🏃 完整数据访问 - 锻炼、恢复、睡眠、周期和个人资料信息 🤖 自然语言查询 - 用简单的英语向 Claude 询问您的健身数据 ⚡ 智能缓存 - 通过智能数据缓存优化性能 🛡️ 隐私至上 - 所有数据保留在您的机器上，绝不发送给第三方 🔄 自动令牌刷新 - 通过自动身份验证更新实现无缝体验

Related MCP server: Whoop MCP Server

🚀 快速入门

🎯 选择您的部署方式

选项 A：Smithery 托管（推荐初学者）

• ✅ 无安装复杂性

• ✅ 自动更新和维护

• ✅ 企业级托管

• ➡️ 开始使用 Smithery

选项 B：本地安装（高级用户）

• ✅ 完全控制和隐私

• ✅ 无外部依赖

• ✅ 自定义和扩展

• ➡️ 继续阅读下方的本地设置

📦 本地安装

1. 先决条件

• Python 3.8+

• Claude Desktop

• 有效的 WHOOP 账户

2. 安装

git clone https://github.com/romanevstigneev/whoop-mcp-server.git
cd whoop-mcp-server
pip install -r requirements.txt

3. 设置

选项 A：交互式设置（推荐）

运行交互式设置：

python setup.py

这将：

• 打开浏览器进行 WHOOP OAuth 授权

• 在本地安全保存您的令牌

• 提供 Claude Desktop 配置

选项 B：手动 WHOOP OAuth 设置

如果交互式设置不起作用，您可以手动获取 WHOOP 令牌：

1. 打开 WHOOP OAuth 页面： 👉 点击此处授权 WHOOP 访问

2. 授权您的账户：

   • 使用您的 WHOOP 凭据登录

   • 授予所请求范围的权限：

     • read:profile - 访问您的个人资料信息

     • read:workout - 访问锻炼数据

     • read:recovery - 访问恢复数据

     • read:sleep - 访问睡眠数据

     • offline - 用于持续访问的刷新令牌

3. 复制授权码：

   • 授权后，您将看到一个成功页面

   • 复制整个授权码（以字母/数字开头的长字符串）

   • 看起来像：ABC123...XYZ789（长得多）

4. 用代码交换令牌：

   python -c "
   import sys
   sys.path.insert(0, './src')
   from auth_manager import TokenManager
   import requests
   
   # Paste your authorization code here
   auth_code = 'YOUR_AUTHORIZATION_CODE_HERE'
   
   # Exchange for tokens
   url = f'https://personal-integrations-462307.uc.r.appspot.com/api/get-tokens/{auth_code}'
   response = requests.get(url, timeout=30)
   
   if response.status_code == 200:
       token_data = response.json()
       if token_data.get('success'):
           # Save tokens
           token_manager = TokenManager()
           token_manager.save_tokens(token_data)
           print('✅ Tokens saved successfully!')
       else:
           print('❌ Token exchange failed')
   else:
       print(f'❌ HTTP Error: {response.status_code}')
   "

5. 验证设置：

   python -c "
   import sys
   sys.path.insert(0, './src')
   from whoop_client import WhoopClient
   client = WhoopClient()
   print(f'✅ Auth status: {client.get_auth_status()}')
   "

4. 配置 Claude Desktop

添加到您的 Claude Desktop 设置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "whoop": {
      "command": "/opt/miniconda3/bin/python",
      "args": ["/path/to/whoop-mcp-server/src/whoop_mcp_server.py"],
      "env": {
        "PYTHONPATH": "/path/to/whoop-mcp-server/src"
      }
    }
  }
}

⚠️ 重要：使用完整的 Python 路径（通过 which python3 查找您的路径）

5. 重启 Claude Desktop

添加配置后，重启 Claude Desktop 以加载 WHOOP 服务器。

💡 使用示例

配置完成后，您可以询问 Claude：

• "Show my WHOOP profile" (显示我的 WHOOP 个人资料)

• "What were my workouts this week?" (我这周的锻炼情况如何？)

• "How is my recovery trending?" (我的恢复趋势如何？)

• "Show my sleep data for the last 7 days" (显示我过去 7 天的睡眠数据)

• "What's my HRV looking like?" (我的 HRV 怎么样？)

• "Compare my recovery to last month" (将我的恢复情况与上个月进行比较)

🛠️ 可用工具

get_whoop_profile

获取您的 WHOOP 用户个人资料信息。

get_whoop_workouts

获取带有可选过滤器的锻炼数据：

• start_date (YYYY-MM-DD)

• end_date (YYYY-MM-DD)

• limit (结果数量)

get_whoop_recovery

获取带有可选过滤器的恢复数据：

• start_date (YYYY-MM-DD)

• end_date (YYYY-MM-DD)

• limit (结果数量)

get_whoop_sleep

获取带有可选过滤器的睡眠数据：

• start_date (YYYY-MM-DD)

• end_date (YYYY-MM-DD)

• limit (结果数量)

get_whoop_cycles

获取带有可选过滤器的生理周期（每日数据）：

• start_date (YYYY-MM-DD)

• end_date (YYYY-MM-DD)

• limit (结果数量)

get_whoop_auth_status

检查身份验证状态和令牌信息。

clear_whoop_cache

清除缓存数据以强制进行新的 API 调用。

🔐 安全性

• 令牌加密：所有令牌在静态时均使用 AES 加密

• 本地存储：令牌存储在您的本地机器上，绝不发送给第三方

• 安全权限：令牌文件具有受限权限 (600)

• 自动刷新：令牌在过期时会自动刷新

📊 数据缓存

• 智能缓存：API 响应缓存 5 分钟以提高性能

• 速率限制：内置速率限制以遵守 WHOOP API 限制

• 缓存控制：可手动清除缓存

🔧 配置

环境变量（可选）：

• LOG_LEVEL：日志级别 (DEBUG, INFO, WARNING, ERROR)

• LOG_FILE：日志文件路径（默认：仅控制台）

🆚 部署对比

📁 文件结构

whoop-mcp-server/
├── src/                       # Python local installation
│   ├── whoop_mcp_server.py    # Main MCP server
│   ├── whoop_client.py        # WHOOP API client
│   ├── auth_manager.py        # Token management
│   └── config.py              # Configuration
├── smithery/                  # TypeScript source files
│   └── src/
│       ├── index.ts           # Smithery MCP server
│       ├── whoop-client.ts    # TypeScript WHOOP client
│       └── types.ts           # Type definitions
├── storage/                   # Local installation only
│   ├── tokens.json            # Encrypted tokens (auto-generated)
│   └── .encryption_key        # Encryption key (auto-generated)
├── package.json               # Node.js dependencies (Smithery)
├── smithery.yaml              # Smithery configuration (root required)
├── tsconfig.json              # TypeScript configuration
├── setup.py                   # Interactive setup script
└── requirements.txt           # Python dependencies

🐛 故障排除

"No valid access token available" (没有有效的访问令牌)

• 运行 python setup.py 重新授权

• 检查您的 WHOOP 账户是否处于活动状态

"Authentication failed" (身份验证失败)

• 您的令牌可能已过期且无法刷新

• 运行 python setup.py 获取新令牌

"Rate limit exceeded" (超出速率限制)

• 在进行更多请求之前等待一分钟

• 考虑使用缓存数据或降低请求频率

Claude Desktop 看不到服务器

• 使用完整 Python 路径：将 "command": "python" 更改为 "command": "/opt/miniconda3/bin/python"（使用 which python3 查找您的路径）

• 检查正确的配置文件：编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（而不是 .claude.json）

• 使用绝对路径：使用完整路径，如 /Users/username/whoop-mcp-server/src/whoop_mcp_server.py

• 检查日志：tail -f ~/Library/Logs/Claude/mcp-server-whoop.log

• 配置更改后重启 Claude Desktop

🔄 令牌刷新

服务器会自动使用刷新令牌来刷新过期的令牌。如果失败，您需要重新授权：

python setup.py

📝 日志记录

默认情况下，日志写入控制台。要记录到文件：

export LOG_FILE="/path/to/whoop-mcp.log"
export LOG_LEVEL="INFO"

🤝 贡献

1. Fork 本仓库

2. 创建功能分支

3. 进行更改

4. 如果适用，添加测试

5. 提交 Pull Request

📄 许可证

本项目采用 MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

⚠️ 免责声明

这是与 WHOOP 的非官方集成。它使用官方 WHOOP API，但未得到 WHOOP 的认可。

📞 支持

• 查看上方的故障排除部分

• 在 GitHub 上提交 Issue

• 查看 WHOOP API 文档：https://developer.whoop.com/

🎯 路线图

• [ ] 历史数据分析

• [ ] 自定义日期范围查询

• [ ] 数据导出功能

• [ ] 实时更新的 Webhook 支持

• [ ] 高级分析和见解