Oura Ring MCP

🚀 Oura Ring MCP Server

This Model Context Protocol (MCP) server offers access to Oura Ring health and fitness data via the Oura API v2.

🚀 Quick Start

This Oura Ring MCP Server allows you to access a wide range of health and fitness data from the Oura Ring. Follow the steps below to get started.

✨ 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:

git clone <repository-url>
cd oura-ring-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

📚 Documentation

Configuration

1. Get Your Oura Access Token

For personal use, create a Personal Access Token:

1. Go to Oura Cloud 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:

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

npm test

2. Test API connectivity (requires your Oura access token):

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:

npm start

Or run in development mode:

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.

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:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31"
}

API Reference

This MCP server is built on the Oura API v2. 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

npm run build

Testing

# Test server instantiation (no API calls)
npm test

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

Linting

npm run lint

Troubleshooting

Common Issues

⚠️ Important Note

• "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
• Oura API Documentation
• Model Context Protocol
• Personal Access Tokens
• OAuth Applications