Oura Ring MCP Server

A Model Context Protocol (MCP) server that provides access to Oura Ring 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:

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

2. Install dependencies:

npm install

3. Build the project:

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
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.

MCP Inspector

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

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

{
  "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

"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