# 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**
```bash
cd /path/to/health_mcp
```
2. **Create a virtual environment**
```bash
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
```
3. **Install dependencies**
```bash
pip install -r requirements.txt
```
4. **Configure API credentials**
Copy the example configuration:
```bash
cp config.example.yaml config.yaml
```
Edit `config.yaml` with your API credentials (configure one or both):
```yaml
# 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**
```bash
# 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](https://developer.whoop.com/)
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](https://www.strava.com/settings/api)
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`
```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:
```json
{
"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
```yaml
# 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:
```python
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
