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

Clone this repository:

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

Install dependencies:

npm install

Build the project:

npm run build

Configuration

1. Get Your Oura Access Token

For personal use, create a Personal Access Token:

Go to Oura Cloud Personal Access Tokens
Click "Create New Personal Access Token"
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:

Register an API Application at Oura Cloud OAuth Applications
Add your OURA_CLIENT_ID and OURA_CLIENT_SECRET to the .env file

Usage

Testing Locally

Test server setup (no API calls needed):

npm test

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

Ensure you have OURA_CLIENT_ID and OURA_CLIENT_SECRET configured
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.