Oura Ring MCP Server

# 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)