mcp-server

# @vitaltrends/mcp-server MCP server for [VitalTrends](https://vitaltrends.net) — query your WHOOP, Oura, Hevy, Withings, and Apple Health data from Claude Desktop using natural language. ``` "What was my average HRV last week compared to the week before?" "On days I ran more than 10 km, how did my recovery score change the next day?" "Give me a weekly summary of sleep performance for April." ``` ## Requirements - [VitalTrends](https://vitaltrends.net) account with an active subscription - A VitalTrends API key (generate one in **Settings → Developer**) - [Claude Desktop](https://claude.ai/download) (Mac or Windows) or another MCP-compatible client - Node.js 18+ ## Setup ### 1. Get your API key Log in to VitalTrends and go to **Settings → Developer**. Click **Generate API key** and copy it. ### 2. Install the package globally ```bash npm install -g @vitaltrends/mcp-server ``` ### 3. Configure Claude Desktop Open the Claude Desktop config file: - **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json` Add the VitalTrends entry inside `"mcpServers"`: ```json { "mcpServers": { "vitaltrends": { "command": "mcp-server", "env": { "VITALTRENDS_API_KEY": "YOUR_API_KEY" } } } } ``` If Claude Desktop can't find `mcp-server`, replace `"mcp-server"` with the full path from `which mcp-server`. ### 4. Restart Claude Desktop Quit and reopen Claude Desktop. You should see a VitalTrends icon in the toolbar indicating the server connected. ## Available tools | Tool | Description | |---|---| | `get_whoop_daily` | Recovery score, HRV, resting heart rate, sleep performance, sleep duration, strain, and `is_partial` for open current cycles | | `get_whoop_recovery_status` | Latest WHOOP recovery freshness, sync, and upstream update timestamps | | `get_whoop_workouts` | Workout history with sport name, duration, strain, heart rate, and distance | | `get_whoop_sleep` | Sleep sessions with stages and performance scores | | `get_unified_workouts` | Cross-source workout feed with WHOOP, Apple Health, Oura, Strava, and Hevy deduplicated into sessions | | `get_hevy_workouts` | Hevy workout records with nested exercises and sets | | `get_oura_daily_sleep` | Daily sleep scores and sleep score contributors | | `get_oura_sleep` | Sleep sessions with stages, duration, HRV, heart rate, and respiratory rate | | `get_oura_daily_readiness` | Daily readiness scores, temperature deviation, and readiness contributors | | `get_oura_daily_activity` | Daily activity scores, calories, steps, distance, active minutes, and activity contributors | | `get_oura_workouts` | Workout sessions with activity, intensity, source, calories, distance, and timestamps | | `get_oura_daily_spo2` | Daily SpO2 averages and breathing disturbance index | | `get_oura_daily_stress` | Daily stress, recovery, and day summary data | | `get_oura_daily_resilience` | Daily resilience level and resilience contributors | | `get_oura_vo2_max` | VO2 max estimates by day | | `get_withings_measurements` | Weight and body composition: weight (kg), fat ratio, fat mass, fat-free mass, muscle mass, and bone mass | | `get_apple_health_daily_summary` | Single-day Apple Health summary with activity, heart, sleep stages, body metrics, and workout metadata | | `get_apple_health_daily` | Daily Apple Health aggregates: steps, energy (kcal), distance (km), heart rate, HRV, SpO2, and sleep | | `get_apple_health_samples` | Per-type Apple Health time series with optional metadata for sleep stages and workout details | | `get_summary` | Cross-source aggregate: avg/min/max recovery, HRV, RHR, sleep performance, strain, workout count, and body composition | List tools accept optional `start` and `end` parameters as `YYYY-MM-DD` dates or ISO 8601 datetimes, a `per_page` parameter (1–200, default 50), and `page` for paginated results. `get_whoop_recovery_status` does not require arguments. `get_apple_health_daily_summary` accepts a single `date` (`YYYY-MM-DD`) and optional comma-separated `types`. ## Development ```bash npm install npm run build # compile TypeScript to dist/ npm test # run tests npm run dev # watch mode ``` ## Publishing ```bash npm run build npm publish --access public ``` ## Security - The API key is read from the `VITALTRENDS_API_KEY` environment variable and is never logged or included in error output. - All requests use HTTPS. - Tool arguments are validated before being sent to the API (date/datetime format, enum values, per_page bounds, page bounds). - Requests time out after 30 seconds. ## License MIT