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

Tool	Description
list_adapters	List all available adapters and their authentication status

Whoop Tools

Authentication

Tool	Description
whoop_authenticate	Initiate OAuth2 login flow for Whoop
whoop_check_auth	Check current authentication status

Profile

Tool	Description
get_user_profile	Get user profile and body measurements

Sleep

Tool	Description
get_sleep_summary	Recent sleep with performance, stages, and needs
get_sleep_history	Sleep history over date range with trends

Recovery

Tool	Description
get_recovery_score	Latest recovery with HRV and status
get_recovery_history	Recovery trends over time

Strain & Workouts

Tool	Description
get_strain_today	Current day strain and heart rate
get_strain_history	Daily strain patterns over time
get_workout_history	Workout details with HR zones and calories

Analysis & Insights

Tool	Description
get_health_overview	Comprehensive health dashboard
analyze_sleep_patterns	Sleep timing, consistency, and recommendations
analyze_recovery_factors	Correlations affecting recovery
get_weekly_report	Week-over-week comparison with trends
get_training_readiness	Workout intensity recommendations

Strava Tools

Authentication

Tool	Description
strava_authenticate	Initiate OAuth2 login flow for Strava
strava_check_auth	Check current Strava authentication status

Profile & Stats

Tool	Description
get_strava_profile	Athlete profile with all-time stats and gear

Activities

Tool	Description
get_strava_activities	Recent activities with distance, pace, HR, etc.
get_strava_activity_detail	Detailed activity with laps, segments, and full stats
get_strava_weekly_summary	Weekly training summary by activity type

Training Zones

Tool	Description
get_strava_zones	Your configured HR and power training zones
get_strava_activity_zones	Zone distribution for a specific activity

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

{
    "mcpServers": {
        "health": {
            "command": "/path/to/health_mcp/venv/bin/python",
            "args": ["-m", "src.server"],
            "cwd": "/path/to/health_mcp",
            "env": {
                "HEALTH_MCP_WHOOP_CLIENT_ID": "your_whoop_client_id",
                "HEALTH_MCP_WHOOP_CLIENT_SECRET": "your_whoop_client_secret",
                "HEALTH_MCP_STRAVA_CLIENT_ID": "your_strava_client_id",
                "HEALTH_MCP_STRAVA_CLIENT_SECRET": "your_strava_client_secret"
            }
        }
    }
}

Usage with Cursor

Add the following to your Cursor MCP settings:

{
  "mcpServers": {
    "health": {
      "command": "/path/to/health_mcp/venv/bin/python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/health_mcp"
    }
  }
}

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

health_mcp/
├── src/
│   ├── __init__.py
│   ├── server.py              # Main MCP server with dynamic adapter loading
│   ├── config.py              # Configuration management
│   ├── auth/
│   │   ├── __init__.py
│   │   ├── oauth_server.py    # Shared OAuth callback server
│   │   └── token_store.py     # Token persistence
│   ├── adapters/
│   │   ├── __init__.py
│   │   ├── base.py            # Abstract adapter interface
│   │   ├── whoop.py           # Whoop API adapter
│   │   └── strava.py          # Strava API adapter
│   └── tools/
│       ├── __init__.py
│       ├── sleep.py           # Whoop sleep tools
│       ├── recovery.py        # Whoop recovery tools
│       ├── strain.py          # Whoop strain & workout tools
│       ├── profile.py         # Whoop profile tools
│       ├── insights.py        # Whoop analysis tools
│       └── strava.py          # Strava-specific tools
├── config.example.yaml
├── requirements.txt
└── README.md

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

# Each adapter section supports:
provider_name:
  client_id: "..."
  client_secret: "..."
  redirect_uri: "http://localhost:8787/callback"
  enabled: true  # Optional: explicitly enable/disable (auto-detected by default)

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:

from .base import HealthAdapter, SleepRecord, RecoveryRecord, WorkoutRecord

class NewProviderAdapter(HealthAdapter):
    provider_name = "new_provider"

    async def is_authenticated(self) -> bool:
        # Check auth status
        pass

    async def authenticate(self) -> bool:
        # Initiate OAuth flow
        pass

    async def get_workouts(self, start=None, end=None, limit=10) -> list[WorkoutRecord]:
        # Implement workout data fetching
        pass

    # Implement other methods (return empty lists for unsupported features)

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