# WHOOP MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the WHOOP API. This server enables LLMs to retrieve sleep, recovery, and physiological cycle data from WHOOP.

## Features

- 🔐 **OAuth 2.0 Authentication** with automatic token refresh
- 😴 **Sleep Data**: Retrieve detailed sleep metrics by ID or cycle
- 🔄 **Cycle Data**: Access physiological cycles with strain and heart rate data
- 💪 **Recovery Data**: Get recovery scores, HRV, and readiness metrics
- 🚀 **Built with xmcp**: Fast, type-safe MCP implementation

## Prerequisites

- Node.js 20 or higher
- A WHOOP account
- WHOOP API credentials (Client ID and Secret)

## Getting WHOOP API Credentials

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

## Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/whoop-mcp.git
cd whoop-mcp

# Install dependencies
pnpm install
# or npm install

# Build the project
pnpm build
# or npm run build
```

## Configuration

1. Copy the environment template:
```bash
cp .env.example .env
```

2. Add your WHOOP credentials to `.env`:
```env
WHOOP_CLIENT_ID=your_client_id_here
WHOOP_CLIENT_SECRET=your_client_secret_here
```

## Authentication

Before using the MCP server, you need to authenticate with WHOOP:

```bash
pnpm auth
```

This will:
1. Open a browser window for WHOOP OAuth login
2. Save your access and refresh tokens locally
3. Automatically refresh tokens when they expire

## Usage

### Using with Claude Desktop - STDIO Mode (Recommended)

STDIO mode is recommended for better performance and reliability.

1. Get the full path to your installation:
```bash
pwd  # Copy this path, e.g., /Users/yourname/projects/whoop-mcp
```

2. Add the server to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "whoop": {
      "command": "node",
      "args": ["/Users/yourname/projects/whoop-mcp/dist/stdio.js"],
      "env": {
        "WHOOP_CLIENT_ID": "your-client-id",
        "WHOOP_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

Replace `/Users/yourname/projects/whoop-mcp` with your actual installation path.

### Using via HTTP Mode

For HTTP mode, start the server:

```bash
pnpm start
# or
node dist/http.js
```

The server will run on `http://localhost:3002/mcp`

For Claude Desktop HTTP configuration:
```json
{
  "mcpServers": {
    "whoop": {
      "url": "http://localhost:3002/mcp"
    }
  }
}
```

**Important**: When using STDIO mode with Claude Desktop, you MUST include the `env` section with your WHOOP credentials, as shown above. The server cannot read your `.env` file when launched by Claude Desktop.

See [xmcp HTTP transport documentation](https://xmcp.dev/docs#http-transport) for more details.

### Development Mode

```bash
pnpm dev
```

## Available Tools

### `get-recent-cycles`
Retrieves recent physiological cycles (days) with strain and heart rate data.

**Parameters:**
- `limit` (number, optional): Number of cycles to retrieve (1-25, default: 10)
- `days` (number, optional): Number of days to look back (1-30)

**Example:**
```
Get my last 7 days of WHOOP cycles
```

### `get-sleep-by-id`
Gets detailed sleep data for a specific sleep ID.

**Parameters:**
- `sleepId` (string): UUID of the sleep activity

**Example:**
```
Get sleep data for ID ecfc6a15-4661-442f-a9a4-f160dd7afae8
```

### `get-sleep-for-cycle`
Retrieves sleep data associated with a specific cycle.

**Parameters:**
- `cycleId` (number): ID of the cycle

**Example:**
```
Get sleep data for cycle 12345
```

### `get-recovery-for-cycle`
Gets recovery metrics for a specific cycle, including HRV and readiness scores.

**Parameters:**
- `cycleId` (number): ID of the cycle

**Example:**
```
Get recovery data for cycle 12345
```

## Data Interpretation

### Recovery Scores
- **Green (67-100%)**: Ready for high strain
- **Yellow (34-66%)**: Moderate readiness  
- **Red (0-33%)**: Focus on recovery

### Strain Scale
- WHOOP Strain is measured on a scale from 0 to 21
- Higher values indicate greater cardiovascular load

## Project Structure

```
whoop-mcp/
├── src/
│   ├── api/           # WHOOP API client and types
│   ├── auth/          # Authentication and token management
│   └── tools/         # MCP tool implementations
├── scripts/
│   ├── auth.ts        # OAuth authentication script
│   └── refresh-token.ts # Manual token refresh
└── dist/              # Compiled output
```

## Token Management

- Tokens are stored in `.whoop-tokens.json` in the project root
- Access tokens expire after 1 hour
- Refresh tokens are automatically used to obtain new access tokens
- Run `pnpm refresh-token` to manually refresh tokens

## Troubleshooting

### "Not authenticated" error
Run `pnpm auth` to authenticate with WHOOP.

### "Resource not found" error
Ensure your WHOOP app has the required scopes:
- `read:cycles`
- `read:sleep` 
- `read:recovery`
- `read:profile`
- `offline` (for refresh tokens)

### Rate limiting
WHOOP API has rate limits. If you encounter 429 errors, wait before making more requests.

## Development

```bash
# Build the project
pnpm build

# Run in development mode
pnpm dev

# Manually refresh tokens
pnpm refresh-token
```

## Security Notes

- Never commit `.env` or `.whoop-tokens.json` files
- Keep your Client Secret secure
- Tokens are stored in the project root as `.whoop-tokens.json`
- Tokens are never transmitted except to WHOOP

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## License

MIT - See LICENSE file for details

## Acknowledgments

- Built with [xmcp](https://github.com/zerdos/xmcp) - Fast MCP implementation
- Uses the [WHOOP API v2](https://developer.whoop.com/api)

## Additional Resources

- [xmcp Documentation - Using Tools](https://xmcp.dev/docs#using-tools)
- [xmcp Documentation](https://xmcp.dev/docs)
- [Model Context Protocol Specification](https://spec.modelcontextprotocol.io/)

## Support

For WHOOP API issues, visit the [WHOOP Developer Documentation](https://developer.whoop.com/docs/developing-your-app).

For MCP-related questions, see the [Model Context Protocol documentation](https://modelcontextprotocol.io/).