# WHOOP MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for the [WHOOP API](https://developer.whoop.com/). Gives any MCP-compatible client (Claude Code, Claude Desktop, etc.) read access to your WHOOP biometric data -- recovery, sleep, strain, workouts, and more.

## Features

- Full coverage of the WHOOP Developer API v2
- OAuth 2.0 authentication with token refresh
- Sleep analysis (stages, efficiency, respiratory rate)
- Recovery scores (HRV, resting heart rate, SpO2, skin temp)
- Strain and cycle data
- Workout tracking with heart rate zones
- Pagination support for all collection endpoints
- TypeScript with full type definitions

## Prerequisites

- **Node.js 18+**
- **WHOOP account** with an active membership
- **WHOOP Developer App** -- register at [developer.whoop.com](https://developer.whoop.com/)

## Quick Start

### 1. Clone and install

```bash
git clone https://github.com/AaronRoeF/whoop-mcp-server.git
cd whoop-mcp-server
npm install
```

### 2. Register a WHOOP Developer App

1. Go to [developer.whoop.com](https://developer.whoop.com/)
2. Create a new application
3. Set the redirect URI to `http://localhost:3000/callback`
4. Note your **Client ID** and **Client Secret**

### 3. Configure environment

```bash
cp env.example .env
```

Edit `.env` with your credentials:

```env
WHOOP_CLIENT_ID=your_client_id
WHOOP_CLIENT_SECRET=your_client_secret
WHOOP_REDIRECT_URI=http://localhost:3000/callback
```

### 4. Build

```bash
npm run build
```

### 5. Authenticate with WHOOP

```bash
npm run auth
```

This starts a local web server, opens your browser, and walks you through the WHOOP OAuth flow. On success, tokens are saved to `whoop-tokens.json` (gitignored).

### 6. Add to Claude Code

Add to your `~/.claude.json`:

```json
{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp-server/start-mcp-server.js"],
      "cwd": "/absolute/path/to/whoop-mcp-server"
    }
  }
}
```

Or for Claude Desktop, add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/absolute/path/to/whoop-mcp-server/start-mcp-server.js"],
      "cwd": "/absolute/path/to/whoop-mcp-server"
    }
  }
}
```

The `start-mcp-server.js` script automatically loads saved tokens, refreshes them if expired, and starts the MCP server.

## Available Tools

### User

| Tool | Description |
|------|-------------|
| `whoop-get-user-profile` | Get profile info (name, email) for the authenticated user |
| `whoop-get-user-body-measurements` | Get height, weight, and max heart rate |
| `whoop-revoke-user-access` | Revoke the current access token |

### Cycles

| Tool | Description |
|------|-------------|
| `whoop-get-cycle-by-id` | Get a specific physiological cycle by ID |
| `whoop-get-cycle-collection` | Get all cycles (paginated, with date filters) |
| `whoop-get-sleep-for-cycle` | Get sleep data associated with a specific cycle |

### Recovery

| Tool | Description |
|------|-------------|
| `whoop-get-recovery-collection` | Get recovery records (paginated, with date filters) |
| `whoop-get-recovery-for-cycle` | Get recovery data for a specific cycle |

### Sleep

| Tool | Description |
|------|-------------|
| `whoop-get-sleep-by-id` | Get a specific sleep record by ID |
| `whoop-get-sleep-collection` | Get sleep records (paginated, with date filters) |

### Workouts

| Tool | Description |
|------|-------------|
| `whoop-get-workout-by-id` | Get a specific workout record by ID |
| `whoop-get-workout-collection` | Get workout records (paginated, with date filters) |

### OAuth

| Tool | Description |
|------|-------------|
| `whoop-get-authorization-url` | Get the OAuth authorization URL |
| `whoop-exchange-code-for-token` | Exchange an authorization code for an access token |
| `whoop-refresh-token` | Refresh the access token using a refresh token |
| `whoop-set-access-token` | Manually set the access token for API calls |

## OAuth Setup Details

WHOOP uses OAuth 2.0. The flow works like this:

1. **Register your app** at [developer.whoop.com](https://developer.whoop.com/) and set the redirect URI to `http://localhost:3000/callback`
2. **Run `npm run auth`** -- this starts a local server and opens the WHOOP authorization page
3. **Authorize the app** -- log in to your WHOOP account and grant access
4. **Tokens are saved automatically** to `whoop-tokens.json`

Access tokens expire after ~1 hour. The `start-mcp-server.js` script handles automatic refresh on startup. If refresh fails, re-run `npm run auth`.

### Required OAuth Scopes

The server requests these scopes:
- `read:recovery`
- `read:cycles`
- `read:workout`
- `read:sleep`
- `read:profile`
- `read:body_measurement`

## Pagination

Collection endpoints accept these optional parameters:

| Parameter | Type | Description |
|-----------|------|-------------|
| `limit` | number | Max records to return (up to 25) |
| `start` | string | Return records after this time (ISO 8601) |
| `end` | string | Return records before this time (ISO 8601) |
| `nextToken` | string | Pagination token from previous response |

## Project Structure

```
src/
  index.ts          Entry point
  mcp-server.ts     MCP server with tool definitions and handlers
  whoop-api.ts      WHOOP API client (OAuth + all endpoints)
  types.ts          TypeScript type definitions
auth-app.js         Local OAuth web server for initial authentication
start-mcp-server.js MCP server launcher with auto token refresh
env.example         Environment variable template
```

## Development

```bash
npm run build       # Compile TypeScript
npm start           # Run the compiled server
npm run dev         # Run with tsx (hot reload)
npm run auth        # Run the OAuth authentication flow
npm run start-mcp   # Start MCP server with saved tokens
```

## License

MIT -- see [LICENSE](LICENSE) for details.

## Acknowledgments

- [WHOOP Developer Platform](https://developer.whoop.com/) for the API
- [Model Context Protocol](https://modelcontextprotocol.io/) for the MCP specification