Health MCP Server

A Model Context Protocol (MCP) server for aggregating and analyzing health and fitness data from multiple sources. Currently supports Whoop and Strava with an extensible adapter architecture for future integrations (Withings, Oura, Garmin, etc.).

Features

Multi-Provider Support

• Modular Architecture: Each adapter is optional and independently configurable

• Auto-Enable: Adapters are automatically enabled when credentials are configured

• Unified Auth: Single OAuth callback server shared across all providers

Whoop Integration

• Sleep Analysis: Track sleep duration, stages (deep, REM, light), efficiency, and consistency

• Recovery Tracking: Monitor recovery scores, HRV, resting heart rate, and SpO2

• Strain Monitoring: View daily strain, workout history, and heart rate zones

• Advanced Insights: Get personalized recommendations, trend analysis, and correlations

Strava Integration

• Activity Tracking: View runs, rides, swims, and all activity types with full stats

• Performance Metrics: Distance, pace, speed, elevation, heart rate, power, and cadence

• Training Zones: Heart rate and power zone configuration and per-activity distribution

• Athlete Stats: All-time totals, year-to-date, and recent activity summaries

• Gear Tracking: Monitor distance on bikes, shoes, and other equipment

Available Tools

General

Whoop Tools

Authentication

Profile

Sleep

Recovery

Strain & Workouts

Analysis & Insights

Strava Tools

Authentication

Profile & Stats

Activities

Training Zones

Installation

Prerequisites

• Python 3.10 or higher

• API credentials for at least one provider (Whoop and/or Strava)

Setup

1. Clone the repository

   cd /path/to/health_mcp

2. Create a 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 API credentials

   Copy the example configuration:

   cp config.example.yaml config.yaml

   Edit config.yaml with your API credentials (configure one or both):

   # Whoop - Get credentials from https://developer.whoop.com/ whoop: client_id: "your_client_id_here" client_secret: "your_client_secret_here" redirect_uri: "http://localhost:8787/callback" # Strava - Get credentials from https://www.strava.com/settings/api strava: client_id: "your_client_id_here" client_secret: "your_client_secret_here" redirect_uri: "http://localhost:8787/callback"

   Alternative: Environment Variables

   # Whoop export HEALTH_MCP_WHOOP_CLIENT_ID="your_client_id" export HEALTH_MCP_WHOOP_CLIENT_SECRET="your_client_secret" # Strava export HEALTH_MCP_STRAVA_CLIENT_ID="your_client_id" export HEALTH_MCP_STRAVA_CLIENT_SECRET="your_client_secret"

Getting API Credentials

Whoop

1. Go to Whoop Developer Portal

2. Create a new application

3. Set the redirect URI to http://localhost:8787/callback

4. Copy your Client ID and Client Secret

Strava

1. Go to Strava API Settings

2. Create a new application (or use an existing one)

3. Set the "Authorization Callback Domain" to localhost

4. Copy your Client ID and Client Secret

Usage with Claude Desktop

Add the following to your Claude Desktop configuration file:

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

Usage with Cursor

Add the following to your Cursor MCP settings:

First-Time Authentication

After setting up the MCP server, authenticate with each provider you've configured:

Whoop

1. Ask the AI: "Authenticate with my Whoop account"

2. A browser window will open for OAuth authorization

3. Log in and authorize the application

4. The token is automatically saved

Strava

1. Ask the AI: "Authenticate with my Strava account"

2. A browser window will open for Strava OAuth

3. Authorize the requested permissions

4. The token is automatically saved

You can check which adapters are available and authenticated by asking: "List my health adapters"

Example Questions

Whoop-Specific

• "How did I sleep last night?"

• "What's my recovery score today?"

• "Show me my sleep trends for the past month"

• "Am I ready for a hard workout today?"

• "What factors are affecting my recovery?"

Strava-Specific

• "Show me my recent Strava activities"

• "What's my weekly training summary?"

• "Show me details for my last run"

• "What are my training zones?"

• "How much have I cycled this year?"

Combined Analysis (when both are connected)

• "Compare my workout strain from Whoop with my Strava activities"

• "Show me my overall fitness status"

• "How does my training load look across all sources?"

Project Structure

Adapter Architecture

The server uses a modular adapter pattern:

• Optional Adapters: Each adapter is optional and independently enabled

• Auto-Discovery: Adapters are automatically enabled when credentials are present

• Explicit Control: Use enabled: true/false in config to override auto-detection

• Unified Interface: All adapters implement a common base class for consistency

• Provider-Specific Tools: Each adapter can expose unique tools for provider-specific features

Configuration Options

Extending with New Adapters

To add a new health data provider:

1. Create a new adapter in src/adapters/ implementing the HealthAdapter base class

2. Add configuration properties in src/config.py

3. Create provider-specific tools in src/tools/

4. Register the adapter and tools in src/server.py

Example adapter skeleton:

Token Storage

OAuth tokens are stored securely at ~/.health_mcp/tokens.json with restricted file permissions (600). Tokens are automatically refreshed when expired.

Troubleshooting

"Not authenticated" errors

Run the appropriate authenticate tool:

• Whoop: whoop_authenticate

• Strava: strava_authenticate

"Missing configuration" errors

Ensure your config.yaml is set up correctly or environment variables are exported.

OAuth callback fails

• Ensure port 8787 is available

• Check that your redirect URI matches exactly in the provider's developer portal

• For Strava, ensure the Authorization Callback Domain is set to localhost

Token refresh fails

Delete ~/.health_mcp/tokens.json and re-authenticate.

Adapter not showing up

• Check that credentials are configured correctly

• Use list_adapters tool to see adapter status

• Check server logs for initialization errors

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit pull requests for:

• New health data adapters (Withings, Oura, Garmin, Apple Health, etc.)

• Additional analysis tools

• Bug fixes and improvements