呼啦-MCP服务器

Name: 呼啦-MCP服务器
Author: RomanEvstigneev

作者：RomanEvstigneev12 星标更新：2025-07-23

安装使用来源：spider==github.com

项目介绍

🏃 WHOOP MCP Server

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

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

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

✨ 特性

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

🚀 快速开始

🎯 选择您的部署方法

选项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令牌：

打开WHOOP OAuth页面： 👉 点击此处授权WHOOP访问
授权您的账户：
- 使用您的WHOOP凭据登录
- 授权请求的范围：
  - read:profile - 访问您的用户资料信息
  - read:workout - 访问锻炼数据
  - read:recovery - 访问恢复数据
  - read:sleep - 访问睡眠数据
  - offline - 刷新令牌以持续访问
复制授权码：
- 授权后，您会看到一个成功页面
- 复制整个授权码（以字母或数字开头的长字符串）
- 它看起来像这样：ABC123...XYZ789（更长）

交换代码以获取令牌：

python -c "
import sys
sys.path.insert(0, './src')
from auth_manager import TokenManager
import requests

# 在这里粘贴您的授权码
auth_code = 'YOUR_AUTHORIZATION_CODE_HERE'

# 交换令牌
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'):
        # 保存令牌
        token_manager = TokenManager()
        token_manager.save_tokens(token_data)
        print('✅ 令牌保存成功！')
    else:
        print('❌ 令牌交换失败')
else:
    print(f'❌ HTTP错误：{response.status_code}')
"

验证设置：

python -c "
import sys
sys.path.insert(0, './src')
from whoop_client import WhoopClient
client = WhoopClient()
print(f'✅ 认证状态：{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提问：

“显示我的WHOOP用户资料”
“本周我的锻炼是什么？”
“我的恢复趋势如何？”
“过去7天的睡眠数据”
“HRV看起来怎么样？”
“与上个月相比，我的恢复情况如何？”

🛠️ 可用工具

`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：日志文件路径（默认：仅控制台）

🆚 部署比较

功能	Smithery托管	本地安装
设置时间	⚡ 2分钟	⏱️ 10-15分钟
复杂度	🟢 初学者友好	🟡 技术设置所需
维护	✅ 零（自动更新）	🔧 手动更新需要
性能	🚀 优化托管	💻 取决于本地设置
隐私	🌐 托管平台	🔒 完全本地
依赖项	❌ 无	🐍 Python, 包, OAuth
故障排除	📞 平台支持	🛠️ 自助服务

📁 文件结构

whoop-mcp-server/
├── src/                       # Python本地安装
│   ├── whoop_mcp_server.py    # 主MCP服务器
│   ├── whoop_client.py        # WHOOP API客户端
│   ├── auth_manager.py        # 令牌管理
│   └── config.py              # 配置
├── smithery/                  # TypeScript源文件
│   └── src/
│       ├── index.ts           # Smithery MCP服务器
│       ├── whoop-client.ts    # TypeScript WHOOP客户端
│       └── types.ts           # 类型定义
├── storage/                   # 本地安装仅
│   ├── tokens.json            # 加密令牌（自动生成）
│   └── .encryption_key        # 加密密钥（自动生成）
├── package.json               # Node.js依赖项（Smithery）
├── smithery.yaml              # Smithery配置（根目录需要）
├── tsconfig.json              # TypeScript配置
├── setup.py                   # 交互式设置脚本
└── requirements.txt           # Python依赖项

🐛 故障排除

“没有有效的访问令牌”

运行python setup.py重新授权
检查您的WHOOP账户是否活跃

“认证失败”

您的令牌可能已过期且无法刷新
运行python setup.py获取新令牌

“超出速率限制”

等待一分钟后再进行更多请求
考虑使用缓存数据或减少请求频率

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"

🤝 贡献

分叉仓库
创建功能分支
进行更改
如适用，添加测试
提交拉取请求

📄 许可

此项目根据MIT许可发布 - 查看LICENSE文件了解详情。

⚠️ 免责声明

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

📞 支持

查看上面的故障排除部分
在GitHub上打开问题
查阅WHOOP API文档：https://developer.whoop.com/