Whoop Fastapi MCP

WHOOP FastAPI+MCP服务器

用于Claude Desktop的全栈WHOOP与FastAPI OAuth服务器和模型上下文协议（MCP）服务器的集成。

🚀 特性

• FastAPI OAuth服务器 -通过WHOOP进行身份验证并访问您的健康数据
• MCP服务器 -将WHOOP数据直接集成到Claude Desktop对话中
• 完成数据访问 -恢复、睡眠、锻炼、周期和身体测量
• 历史查询 -从特定日期或日期范围访问数据
• 安全 -使用加密令牌存储的OAuth 2.0身份验证

📦 包含内容

1.FastAPI应用程序(whoop_simple.py)

用于WHOOP OAuth身份验证和数据探索的Web服务器：

• 带有WHOOP API的OAuth 2.0流程
• 带有健康指标的仪表板
• 所有WHOOP数据的REST API端点
• 令牌缓存实现无缝访问

2.MCP服务器(whoop_mcp_server.py)

用于Claude Desktop集成的模型上下文协议服务器：

• 访问WHOOP数据的8个工具
• 支持历史数据查询
• 恢复评分、睡眠分析、锻炼跟踪
• 循环和应变监测

先决条件

• Python 3.10+
• 带有Python扩展名的VS代码（可选）
• OAuth重定向的HTTPS开发URL（ngrok/cloudflared）
• Claude Desktop（用于MCP集成）
• WHOOP开发人员应用程序凭据来自 developer.hop.com

快速开始

1.安装依赖项

# Create virtual environment
python -m venv .venv

# Activate it
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# Install packages
pip install -r requirements.txt

2.配置环境

# Copy template
cp .env.example .env

编辑 .env 并添加您的凭据：

WHOOP_CLIENT_ID=your_client_id_here
WHOOP_CLIENT_SECRET=your_client_secret_here
PUBLIC_BASE_URL=https://your-ngrok-url.ngrok-free.dev

3.设置OAuth隧道

# Start ngrok
ngrok http 3000

复制HTTPS URL并：

1. 更新 PUBLIC_BASE_URL 在 .env
2. 在中设置回调URL WHOOP开发人员控制台 致：

   https://your-ngrok-url.ngrok-free.dev/callback

4.通过WHOOP进行身份验证

# Start FastAPI server
python whoop_simple.py

# Open browser to http://localhost:3000
# Click "Click here to login with WHOOP"
# Complete OAuth authorization

一旦认证，a .token_cache.json 文件是使用您的OAuth令牌创建的。

5.尝试使用FastAPI端点

• http://localhost:3000/dashboard -健康仪表板
• http://localhost:3000/me -轮廓+身体测量
• http://localhost:3000/daily?day=YYYY-MM-DD -每日循环

6.设置MCP服务器（可选）

对于Claude Desktop集成：

1. 配置Claude桌面：

编辑 %APPDATA%\Claude\claude_desktop_config.json （Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json （Mac）：

   {
     "mcpServers": {
       "whoop-fitness": {
         "command": "C:\\path\\to\\.venv\\Scripts\\python.exe",
         "args": ["C:\\path\\to\\whoop_mcp_server.py"]
       }
     }
   }

1. 重新启动克劳德桌面

1. 克劳德测试：

- “我今天的康复分数是多少？” - “显示我最近7天的数据” - “我昨晚睡得怎么样？”

看 docs/SETUP_MCP.md 了解详细的MCP设置说明。

📖 文档

• QUICKSTART.md -快速设置和运行指南
• SETUP_MCP.md -完成Claude Desktop的MCP服务器设置
• MCP_README.md -MCP服务器文档和可用工具
• 建筑.md -系统架构与设计
• 安全性_CHECKLIST.md -GitHub安全指南

🔧 可用的MCP工具

一旦配置了Claude Desktop，您就可以使用这些工具：

🔐 安全

所有敏感数据都受到保护：

• .env -API凭据（在.gignore中）
• .token_cache.json -OAuth令牌（.gitignore格式）
• .venv/ -虚拟环境（.gitignore格式）

在GitHub上提交和分享是安全的！

🐛 故障排除

FastAPI问题

• 404错误：确保使用 /developer/v2/ API基地
• OAuth回调失败：验证ngrok是否正在运行以及URL是否匹配
• 未返回数据：WHOOP开发人员控制台中的检查范围包括：

- read:profile - read:body_measurement - read:cycles - read:recovery - read:sleep - read:workout

MCP服务器问题

• Claude Desktop看不到服务器：检查配置文件路径并重新启动Claude Desktop
• “找不到访问令牌”：首先通过FastAPI服务器进行身份验证(http://localhost:3000/login)
• 工具未出现：验证配置中的Python路径指向虚拟环境

📝 API终点

FastAPI服务器端点

• GET / -带有链接的主页
• GET /login -启动OAuth流
• GET /callback -OAuth回调处理程序
• GET /me -用户资料和测量
• GET /daily?day=YYYY-MM-DD -特定日期的循环
• GET /dashboard -包含最新数据的健康仪表板

🤝 贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 彻底测试
5. 提交拉取请求

📄 许可证

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

🙏 致谢

• 卫生数据访问的WHOOP API
• 用于AI集成的模型上下文协议（MCP）
• web框架的FastAPI
• Claude Desktop支持MCP