WHOOP MCP Server for Poke

Connect your WHOOP fitness data to Poke AI assistant using the Model Context Protocol (MCP).

---

🎯 What This Does

This MCP server lets you query your WHOOP fitness data through Poke AI assistant using natural language:

• "What's my recovery score today?" - Get your daily recovery metrics
• "How did I sleep last night?" - Analyze your sleep performance
• "Show me my strain data" - View workout strain and heart rate zones
• "What's my biological age?" - Check your WHOOP Age and healthspan metrics

---

✨ Features

• 🏃 5 WHOOP Data Tools: Overview, Sleep, Recovery, Strain, Healthspan
• 🔄 Automatic Token Refresh: Handles authentication seamlessly
• 🌐 Cloud Ready: Deploy to Render with one click
• 🤖 Poke Compatible: Works out of the box with Poke AI

🔑 What Makes This Different

This is a reverse-engineered implementation that directly interfaces with WHOOP's private API. No official SDK, no OAuth flows, no waiting for API approval. Perfect for developers who don't want to go through the hassle of WHOOP's official development program but still want programmatic access to their comprehensive fitness data.

---

🚀 Quick Start

Prerequisites

• Python 3.10 or higher
• WHOOP account with active subscription
• Poke account (for AI assistant integration)
• Render account (free tier works)

Option 1: Deploy to Render (Recommended)

1. Click the "Deploy to Render" button above

2. Configure your deployment:

   • Name: whoop-mcp-server (or your choice)
   • Branch: main

3. Set environment variables:

   • WHOOP_EMAIL: Your WHOOP account email
   • WHOOP_PASSWORD: Your WHOOP account password

4. Wait for deployment (~5-10 minutes)

5. Get your MCP URL:

   https://your-service-name.onrender.com/mcp
   

6. Connect to Poke:

   • Go to https://poke.com/settings/connections/integrations/new
   • Add your MCP URL
   • Start asking questions!

Option 2: Run Locally

1. Clone the repository:

   git clone https://github.com/kabirrgrover/whoop-mcp-poke.git
   cd whoop-mcp-poke
   

2. Create virtual environment:

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure environment:

   cp .env.example .env
   # Edit .env with your WHOOP credentials
   

5. Run the server:

   python src/server.py
   

6. Server runs at: http://localhost:8000/mcp

---

🔧 Configuration

Environment Variables

Variable	Required	Description
WHOOP_EMAIL	✅ Yes	Your WHOOP account email
WHOOP_PASSWORD	✅ Yes	Your WHOOP account password
PORT	❌ No	Server port (default: 8000, auto-set by Render)

WHOOP Credentials

Get your WHOOP credentials:

1. Sign up at https://www.whoop.com
2. Ensure you have an active WHOOP subscription
3. Use your login email and password

Security Note: Your credentials are stored securely in environment variables and never logged or exposed.

---

📱 Using with Poke

Connect to Poke

1. Deploy your server to Render (or run locally with ngrok)
2. Go to https://poke.com/settings/connections/integrations/new
3. Add your MCP server URL
4. Test the connection

Testing the Connection

After connecting to Poke, test with:

"Use the test_connection tool"

You should see: ✅ MCP Server is working! Connection successful.

Available Tools

1. Overview Data

Ask Poke: "What's my WHOOP data for today?"

Returns:

• Recovery score
• Day strain
• Sleep hours
• Calories burned
• HRV, RHR trends
• Today's activities

2. Sleep Analysis

Ask Poke: "How did I sleep last night?"

Returns:

• Sleep performance score
• Hours slept vs needed
• Sleep consistency
• Sleep efficiency
• Insights and recommendations

3. Recovery Metrics

Ask Poke: "What's my recovery score?"

Returns:

• Recovery score (0-100%)
• HRV with trends
• RHR with trends
• Respiratory rate
• Coach insights

4. Strain Tracking

Ask Poke: "Show me my strain data"

Returns:

• Strain score
• Heart rate zone distribution
• Strength activity time
• Steps
• Individual workouts

5. Healthspan

Ask Poke: "What's my biological age?"

Returns:

• WHOOP Age (biological age)
• Age comparison vs chronological
• Pace of aging
• Weekly trends

Example Conversation

User: What's my recovery score today?

Poke: [Calls whoop_get_recovery tool]

Response: Your recovery is 72% (Green - Ready to perform)

📊 Key Metrics:
  • HRV: 65ms (↑ 8% vs baseline)
  • RHR: 52bpm (↓ 3% vs baseline)
  • Sleep Performance: 85%

💡 Coach Insight: "Your recovery is in the green. Your body 
is ready for a high-intensity workout today."

User: Should I do a hard workout?

Poke: Based on your 72% recovery (green zone), yes! Your HRV 
is trending up 8% and your RHR is down 3%, indicating your 
body has recovered well. Your sleep was also strong at 85%. 
This is a great day for high-intensity training.

---

🏗️ Architecture

Poke AI ←→ MCP Server (Render) ←→ WHOOP API
         HTTPS/MCP              HTTPS/AWS Cognito

Technology Stack

• FastMCP 2.0 - MCP server framework
• Python 3.10+ - Runtime
• httpx - Async HTTP client
• Render - Cloud hosting
• AWS Cognito - WHOOP authentication

---

🛠️ Development

Project Structure

whoop-mcp-poke/
├── src/
│   ├── server.py           # FastMCP server
│   ├── whoop_client.py     # WHOOP API client
│   ├── config.py           # Configuration
│   └── tools/
│       └── whoop.py        # Tool handlers
├── requirements.txt        # Python dependencies
├── render.yaml            # Render configuration
└── README.md              # This file

Running Tests

Test your MCP server with the MCP Inspector:

# Start your server
python src/server.py

# In another terminal
npx @modelcontextprotocol/inspector

Open http://localhost:3000 and connect to http://localhost:8000/mcp using "HTTP" transport.

---

🔒 Security

• ✅ Credentials stored in environment variables only
• ✅ WHOOP tokens auto-refresh (24-hour lifetime)
• ✅ No credentials in code or logs
• ✅ HTTPS for all API calls
• ✅ AWS Cognito authentication

Best Practices:

• Never commit .env file
• Use strong WHOOP password
• Rotate credentials if exposed
• Use Render's environment variable encryption

---

🐛 Troubleshooting

"Authentication failed" Error

Solution:

1. Verify your WHOOP email and password in Render environment variables
2. Try logging into https://app.whoop.com with the same credentials
3. Ensure your WHOOP subscription is active

"Invalid MCP server URL" in Poke

Solution:

1. Verify your URL is exactly: https://your-service-name.onrender.com/mcp
2. Check that your Render service is running (green status)
3. Test the endpoint in a browser - you should see JSON response

Deployment Timeout on Render

Solution:

1. Check Render logs for specific errors
2. Verify all environment variables are set
3. Ensure requirements.txt has all dependencies

Server responds but no data returned

Solution:

1. Verify your WHOOP subscription is active
2. Check you have recent WHOOP data (wear your strap!)
3. Try querying data from a specific date: "What was my recovery on 2025-11-01?"

"No module named 'fastmcp'" Error

Solution:

1. Verify requirements.txt has fastmcp>=2.0.0
2. On Render, trigger a manual deploy to reinstall dependencies
3. Check Render logs for failed dependency installation

---

📚 Resources

Documentation

• FastMCP Documentation
• FastMCP GitHub
• MCP Protocol
• Poke Integration Guide
• WHOOP
• Render Documentation

Related Projects

• Poke MCP Template - Official Poke template
• MCP Inspector - Tool for testing MCP servers

---

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

---

📄 License

MIT License - feel free to use this for your own projects!

---

⭐ Acknowledgments

• Built with FastMCP 2.0
• Designed for Poke AI Assistant

---

💬 Support

If you have questions or issues:

1. Check the Troubleshooting section above
2. Open an issue on GitHub
3. Review FastMCP documentation
4. Check Poke's integration guide

---

🚀 Quick Links

• Use This Template: Click "Use this template" button above
• Report Issues: GitHub Issues
• Star on GitHub: Show your support! ⭐

---

Made with ❤️ for the WHOOP and Poke communities

This is an open-source project. Contributions, issues, and feature requests are welcome!