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_IDandOURA_CLIENT_SECRETto the.envfile
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.
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 rangeget_daily_sleep- Get daily sleep summariesget_readiness- Get readiness dataget_daily_readiness- Get daily readiness summaries
Activity & Exercise
get_activity- Get activity dataget_daily_activity- Get daily activity summariesget_workouts- Get workout sessionsget_heart_rate- Get heart rate measurements
Sessions & Wellness
get_sessions- Get breathing, meditation, and nap sessionsget_daily_stress- Get daily stress and recovery dataget_tags- Get user-created tagsget_enhanced_tags- Get enhanced tags with metadata
Time & Configuration
get_sleep_time- Get bedtime and wake time dataget_rest_mode_periods- Get rest mode periodsget_ring_configuration- Get ring settings
Webhooks (Advanced)
get_webhook_subscriptions- List active webhook subscriptionscreate_webhook_subscription- Create new webhook subscriptiondelete_webhook_subscription- Delete webhook subscription
Date Range Parameters
Most tools accept optional date range parameters:
start_date- Start date in YYYY-MM-DD formatend_date- End date in YYYY-MM-DD formatnext_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_IDandOURA_CLIENT_SECRETconfigured - Use the
create_webhook_subscriptiontool with:callback_url- Your endpoint URL (must be HTTPS)verification_token- Secret token for verificationevent_type- Type of events ('create', 'update', 'delete')data_type- Type of data ('sleep', 'activity', etc.)
Webhook Data Types
tag- User tagsenhanced_tag- Enhanced tags with metadataworkout- Exercise sessionssession- Breathing, meditation, nap sessionssleep- Sleep datadaily_sleep- Daily sleep summariesdaily_readiness- Daily readiness summariesdaily_activity- Daily activity summariesdaily_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_TOKENis 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_tokenmatches 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.