lucas-1000/whoop-mcp-server

Whoop MCP Server for ChatGPT

A Model Context Protocol (MCP) server that integrates your Whoop fitness data with ChatGPT, enabling natural language queries about your sleep, recovery, strain, and workout data.

Features

• Search Tool: Query your Whoop data using natural language (e.g., "show me my sleep data from last week")
• Fetch Tool: Retrieve detailed information about specific data points
• Automatic Token Refresh: Handles OAuth token refreshing automatically
• Comprehensive Data Access: Access to sleep, recovery, cycles (strain), and workout data

What You Can Ask ChatGPT

Once connected to ChatGPT, you can ask questions like:

• "What was my recovery score this morning?"
• "Show me my sleep data from last week"
• "How much strain did I accumulate yesterday?"
• "What workouts did I do in the last 7 days?"
• "What's my average HRV over the past month?"
• "How much deep sleep did I get last night?"

Prerequisites

• Node.js 18 or higher
• A Whoop account with API access
• Whoop Developer API credentials (see )

Setup

1. Install Dependencies

npm install

2. Configure Environment Variables

Copy the example environment file and fill in your Whoop API credentials:

cp .env.example .env

Edit .env with your credentials:

WHOOP_CLIENT_ID=your_client_id_here
WHOOP_CLIENT_SECRET=your_client_secret_here
WHOOP_ACCESS_TOKEN=your_access_token_here
WHOOP_REFRESH_TOKEN=your_refresh_token_here

PORT=8000
HOST=0.0.0.0

See for detailed instructions on obtaining these credentials.

3. Build the Project

npm run build

4. Start the Server

For development:

npm run dev

For production:

npm start

The server will start on http://0.0.0.0:8000 by default.

Deployment

Option 1: Deploy to Google Cloud Run (Recommended)

Google Cloud Run provides serverless, auto-scaling deployment with a generous free tier.

Quick Deploy:

chmod +x deploy.sh
./deploy.sh

See for detailed instructions.

Option 2: Deploy to Replit

1. Create a new Repl on Replit
2. Import this repository
3. Add your environment variables in the Secrets panel:
   • WHOOP_CLIENT_ID
   • WHOOP_CLIENT_SECRET
   • WHOOP_ACCESS_TOKEN
   • WHOOP_REFRESH_TOKEN
4. Run the project
5. Get your server URL (should end with /sse/)

Option 3: Deploy to Other Platforms

1. Deploy to any Node.js hosting service (Railway, Render, Fly.io, etc.)
2. Set environment variables in your hosting platform
3. Ensure the server is accessible via HTTPS
4. Note your server URL ending with /sse/

Connecting to ChatGPT

Via ChatGPT UI

1. Go to ChatGPT Settings
2. Navigate to the Connectors tab
3. Click Add Connector or Import Server
4. Enter your MCP server URL: https://your-server.com/sse/
5. The server will appear in your connectors list
6. Enable it in a conversation by selecting "Use Connectors" or "Deep Research"

Via OpenAI API

Include your MCP server in API requests:

curl https://api.openai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{
  "model": "o4-mini-deep-research",
  "input": [
    {
      "role": "developer",
      "content": [
        {
          "type": "input_text",
          "text": "You are a fitness assistant with access to Whoop data."
        }
      ]
    },
    {
      "role": "user",
      "content": [
        {
          "type": "input_text",
          "text": "What was my recovery score today?"
        }
      ]
    }
  ],
  "tools": [
    {
      "type": "mcp",
      "server_label": "whoop",
      "server_url": "https://your-server.com/sse/",
      "allowed_tools": ["search", "fetch"],
      "require_approval": "never"
    }
  ]
}'

API Endpoints

• GET /sse - Server-Sent Events endpoint for MCP communication
• GET /health - Health check endpoint

MCP Tools

search

Search through your Whoop data using natural language queries.

Parameters:

• query (string): Search query (e.g., "sleep last week", "recovery today")

Returns:

• Array of matching results with id, title, text snippet, and URL

Example queries:

• "sleep data from last 7 days"
• "recovery scores this week"
• "workouts yesterday"
• "strain from last month"

fetch

Retrieve detailed information for a specific data item.

Parameters:

• id (string): Item ID in format type:id (e.g., sleep:123, recovery:456)

Returns:

• Complete data object with full details and metadata

Data Types

The server provides access to four main data types:

1. Sleep: Sleep performance, duration, stages (REM, deep, light), respiratory rate
2. Recovery: Recovery score, resting heart rate, HRV, SpO2, skin temperature
3. Cycles (Strain): Daily strain score, heart rate data, kilojoules
4. Workouts: Exercise strain, duration, heart rate, distance (if applicable)

Date Range Parsing

The search tool automatically interprets date ranges from natural language:

• "today" - Current day
• "yesterday" - Previous day
• "last 7 days" / "last week" - Past 7 days
• "last 30 days" / "last month" - Past 30 days
• "last N days" - Past N days (any number)

If no date range is specified, defaults to the last 7 days.

Development

Project Structure

whoop-mcp-server/
├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── whoop-client.ts   # Whoop API client
├── dist/                 # Compiled JavaScript (generated)
├── .env                  # Environment variables (not in git)
├── .env.example          # Example environment file
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Running Tests

# Test the health endpoint
curl http://localhost:8000/health

# Test the SSE endpoint (should keep connection open)
curl http://localhost:8000/sse

Security Considerations

• Never commit your .env file or credentials to version control
• Use HTTPS in production environments
• Regularly rotate your API credentials
• Review the MCP security documentation
• Be cautious about sharing sensitive health data
• Consider implementing additional authentication for your MCP server

Troubleshooting

"Missing required environment variable" error

• Ensure all required variables are set in your .env file
• Check that variable names match exactly (case-sensitive)

"Failed to refresh token" error

• Your refresh token may have expired
• Re-authorize your application (see )
• Verify your client ID and secret are correct

Connection issues with ChatGPT

• Ensure your server URL ends with /sse/
• Verify your server is publicly accessible (not localhost)
• Check that CORS headers are properly set
• Confirm the server is running and the health endpoint responds

No data returned from searches

• Verify you have data in the queried time range on Whoop
• Check that your API tokens have the necessary scopes
• Review server logs for API errors

Resources

• Whoop Developer Documentation
• Model Context Protocol Specification
• OpenAI MCP Guide

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

For issues related to:

• Whoop API: Contact Whoop Developer Support
• MCP Protocol: See MCP Documentation
• This Server: Open an issue in this repository