# Oura Ring MCP Server

A Model Context Protocol (MCP) server that provides access to [Oura Ring](https://ouraring.com/) health and fitness data through the Oura API v2.

## Features

This MCP server exposes all major Oura Ring data types as tools:

### Health & Fitness Data
- **Personal Info** - User profile information (age, weight, height, biological sex, timezone)
- **Sleep Data** - Sleep scores, sleep stages, sleep contributors
- **Activity Data** - Steps, calories, activity levels, MET minutes
- **Readiness Data** - Daily readiness scores and contributing factors
- **Heart Rate** - Heart rate measurements with timestamps and sources

### Daily Summaries
- **Daily Activity** - Daily activity summaries with scores and metrics
- **Daily Sleep** - Daily sleep summaries with scores and contributors  
- **Daily Readiness** - Daily readiness summaries with temperature data
- **Daily Stress** - Daily stress levels and recovery metrics

### Sessions & Workouts
- **Workouts** - Exercise sessions with activity type, duration, calories, distance
- **Sessions** - Breathing exercises, meditation, naps, relaxation sessions
- **Tags** - User-created tags and enhanced tags with metadata

### Configuration & Time Data
- **Sleep Time** - Bedtime and wake time data
- **Rest Mode Periods** - Rest mode periods when enabled
- **Ring Configuration** - Ring settings and preferences

### Webhooks (Advanced)
- **Webhook Management** - Create, list, and delete webhook subscriptions for real-time data updates

## Installation

1. Clone this repository:
```bash
git clone <repository-url>
cd oura-ring-mcp
```

2. Install dependencies:
```bash
npm install
```

3. Build the project:
```bash
npm run build
```

## Configuration

### 1. Get Your Oura Access Token

For personal use, create a Personal Access Token:
1. Go to [Oura Cloud Personal Access Tokens](https://cloud.ouraring.com/personal-access-tokens)
2. Click "Create New Personal Access Token"
3. Copy the generated token

### 2. Environment Setup

Create a `.env` file in the project root:

```bash
# Required: Your Oura Ring Personal Access Token
OURA_ACCESS_TOKEN=your_personal_access_token_here

# Optional: For webhook functionality only
OURA_CLIENT_ID=your_client_id_here
OURA_CLIENT_SECRET=your_client_secret_here

# Optional: Override the default API base URL (usually not needed)
# OURA_BASE_URL=https://api.ouraring.com
```

### 3. For Webhook Functionality (Optional)

If you want to use webhooks for real-time data updates:
1. Register an API Application at [Oura Cloud OAuth Applications](https://cloud.ouraring.com/oauth/applications)
2. Add your `OURA_CLIENT_ID` and `OURA_CLIENT_SECRET` to the `.env` file

## Usage

### Testing Locally

1. **Test server setup** (no API calls needed):
```bash
npm test
```

2. **Test API connectivity** (requires your Oura access token):
```bash
npm run test:api
```
This will test actual API calls to verify your credentials and show sample data.

### Running the MCP Server

Start the MCP server for use with MCP clients:
```bash
npm start
```

Or run in development mode:
```bash
npm run dev
```

**Note**: The server runs on stdio transport and waits for MCP protocol messages. You need an MCP client (like Claude Desktop, Continue, or other MCP-compatible tools) to interact with it.

### MCP Inspector

Use the official MCP Inspector to explore and debug your server:

```bash
# First build your server
npm run build

# Then run the inspector
npm run inspector
```

This opens a web interface at http://localhost:5173 where you can:
- Test all 17+ available tools with custom inputs
- Browse resources and view server capabilities  
- Monitor real-time server communications
- Debug tool parameters and responses

See [INSPECTOR.md](./INSPECTOR.md) for detailed usage instructions.

### Available Tools

#### Personal Information
- `get_personal_info` - Get user personal information

#### Sleep & Readiness
- `get_sleep` - Get sleep data with optional date range
- `get_daily_sleep` - Get daily sleep summaries
- `get_readiness` - Get readiness data
- `get_daily_readiness` - Get daily readiness summaries

#### Activity & Exercise
- `get_activity` - Get activity data
- `get_daily_activity` - Get daily activity summaries
- `get_workouts` - Get workout sessions
- `get_heart_rate` - Get heart rate measurements

#### Sessions & Wellness
- `get_sessions` - Get breathing, meditation, and nap sessions
- `get_daily_stress` - Get daily stress and recovery data
- `get_tags` - Get user-created tags
- `get_enhanced_tags` - Get enhanced tags with metadata

#### Time & Configuration
- `get_sleep_time` - Get bedtime and wake time data
- `get_rest_mode_periods` - Get rest mode periods
- `get_ring_configuration` - Get ring settings

#### Webhooks (Advanced)
- `get_webhook_subscriptions` - List active webhook subscriptions
- `create_webhook_subscription` - Create new webhook subscription
- `delete_webhook_subscription` - Delete webhook subscription

### Date Range Parameters

Most tools accept optional date range parameters:
- `start_date` - Start date in YYYY-MM-DD format
- `end_date` - End date in YYYY-MM-DD format  
- `next_token` - Pagination token for large datasets

Example:
```json
{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}
```

## API Reference

This MCP server is built on the [Oura API v2](https://cloud.ouraring.com/v2/docs). Key features:

### Authentication
- Uses Bearer token authentication with Personal Access Tokens
- Webhook operations require OAuth2 application credentials

### Rate Limits
- 5000 requests per 5-minute period
- Webhooks are recommended to minimize API calls

### Data Types
All data is returned as structured JSON with proper typing and validation using Zod schemas.

### Error Handling
- Comprehensive error handling for API errors, network issues, and invalid responses
- Detailed error messages with status codes when available

## Webhooks

Webhooks provide real-time notifications when your Oura data changes. This is the recommended approach for applications that need up-to-date data.

### Setting Up Webhooks

1. Ensure you have `OURA_CLIENT_ID` and `OURA_CLIENT_SECRET` configured
2. Use the `create_webhook_subscription` tool with:
   - `callback_url` - Your endpoint URL (must be HTTPS)
   - `verification_token` - Secret token for verification
   - `event_type` - Type of events ('create', 'update', 'delete')
   - `data_type` - Type of data ('sleep', 'activity', etc.)

### Webhook Data Types
- `tag` - User tags
- `enhanced_tag` - Enhanced tags with metadata
- `workout` - Exercise sessions
- `session` - Breathing, meditation, nap sessions
- `sleep` - Sleep data
- `daily_sleep` - Daily sleep summaries
- `daily_readiness` - Daily readiness summaries
- `daily_activity` - Daily activity summaries
- `daily_stress` - Daily stress data

## Development

### Project Structure
```
src/
├── types.ts          # TypeScript types and Zod schemas
├── oura-client.ts    # Oura API client implementation
├── server.ts         # MCP server implementation
└── index.ts          # Main entry point

test/
├── test.ts           # Basic server instantiation test
├── manual-test.ts    # API connectivity test with real credentials
└── debug-test.ts     # Raw API response debugging tool
```

### Building
```bash
npm run build
```

### Testing
```bash
# Test server instantiation (no API calls)
npm test

# Test actual API connectivity with your credentials
npm run test:api
```

### Linting
```bash
npm run lint
```

## Troubleshooting

### Common Issues

**"Invalid or expired authentication token"**
- Check that your `OURA_ACCESS_TOKEN` is correct
- Verify the token hasn't expired
- Ensure you're using a Personal Access Token from the correct Oura account

**"Access forbidden" (403 error)**
- Your Oura subscription may have expired
- Some data types require an active Oura subscription

**Rate limit exceeded (429 error)**
- You've exceeded 5000 requests in 5 minutes
- Consider using webhooks to reduce API calls
- Implement proper rate limiting in your application

**Webhook verification failed**
- Ensure your webhook endpoint properly handles the verification challenge
- Check that your `verification_token` matches what you provided
- Verify your endpoint responds with the challenge in the correct format

## License

MIT License - see LICENSE file for details.

## Contributing

Contributions are welcome! Please read the contributing guidelines and submit pull requests for any improvements.

## Links

- [Oura Ring](https://ouraring.com/)
- [Oura API Documentation](https://cloud.ouraring.com/v2/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Personal Access Tokens](https://cloud.ouraring.com/personal-access-tokens)
- [OAuth Applications](https://cloud.ouraring.com/oauth/applications)