Oura Ring MCP Server

A Model Context Protocol (MCP) server that provides seamless access to your Oura Ring health and fitness data. Built with Python and FastMCP, this server enables AI assistants like Claude to query your sleep, activity, readiness, and other health metrics.

Features

• Comprehensive Health Data Access: 15+ data endpoints covering all major Oura Ring metrics

• Simple Authentication: Personal Access Token support for easy setup

• FastMCP Integration: Built on the FastMCP framework for reliable MCP protocol support

• AWS Bedrock Ready: Includes deployment scripts and configuration for AWS Bedrock AgentCore

• Date Range Queries: Flexible date filtering for all metrics

• Type-Safe: Fully typed Python implementation

Available Tools

The server provides the following tools to query your Oura Ring data:

Sleep & Recovery

• get_daily_sleep - Daily sleep scores, duration, efficiency, and sleep stages

• get_sleep_sessions - Detailed sleep sessions with heart rate, HRV, and movement

• get_sleep_time - Sleep timing information (bedtime and wake time)

• get_daily_readiness - Daily readiness scores and contributing factors

Activity & Exercise

• get_daily_activity - Steps, calories, and activity levels

• get_workouts - Workout sessions with activity type, duration, and intensity

• get_sessions - Meditation, breathing exercises, and other sessions

Health Metrics

• get_daily_spo2 - Blood oxygen saturation levels

• get_daily_stress - Stress levels and recovery status

• get_daily_resilience - Resilience scores and trends

• get_daily_cardiovascular_age - Cardiovascular age estimates

• get_vo2_max - VO2 max measurements and trends

Device & Profile

• get_ring_configuration - Ring hardware configuration

• get_rest_mode_period - Rest mode periods

• get_personal_info - User profile information

All date-based tools accept optional start_date and end_date parameters in YYYY-MM-DD format. If not provided, defaults to the last 30 days.

Quick Start

Prerequisites

• Python 3.10 or higher

• An Oura Ring and account

• Oura Personal Access Token (get one at cloud.ouraring.com/personal-access-tokens)

Installation

1. Clone this repository:

2. Install dependencies:

3. Create a .env file with your Oura credentials:

4. Run the server:

Note: The server runs silently and waits for MCP protocol messages. To verify it's working, use the test script (see Testing section below).

Testing

Before configuring with Claude Desktop or deploying to AWS, test your setup:

This will:

• Verify your Oura API token is valid

• Test connection to the Oura API

• Retrieve sample data (personal info, sleep, readiness)

• Confirm all tools are working

Expected output:

If tests fail, verify:

• Your OURA_PERSONAL_ACCESS_TOKEN is correct in .env

• Your Oura Ring has synced recent data

• You have internet connectivity

Configuration for Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%/Claude/claude_desktop_config.json

After adding the configuration, restart Claude Desktop.

AWS Bedrock Deployment

This server is ready to deploy to AWS Bedrock AgentCore. Follow these steps:

Prerequisites

• AWS CLI installed and configured

• Docker installed

• AWS account with Bedrock access

• Your Oura Personal Access Token

Automated Deployment

Run the deployment script:

The script will:

1. Create an ECR repository

2. Build and push the Docker image

3. Set up IAM roles for Bedrock

4. Store your Oura token in AWS Secrets Manager

5. Provide instructions for creating the Bedrock Agent

Manual Deployment Steps

If you prefer manual deployment:

1. Build and push Docker image:

2. Store secrets in AWS Secrets Manager:

3. Create Bedrock Agent:

   • Go to AWS Bedrock Console

   • Create a new Agent

   • Configure MCP server with your container image

   • Add environment variables from Secrets Manager

   • Test the agent

Usage Examples

Once configured with Claude Desktop or Bedrock, you can ask questions like:

• "Show me my sleep data from last week"

• "What was my readiness score yesterday?"

• "How many steps did I take this month?"

• "What's my average heart rate variability?"

• "Am I getting enough deep sleep?"

• "Show me my workout history for this week"

Development

Project Structure

Running Tests

Code Quality

API Reference

OuraClient

The OuraClient class handles authentication and API requests:

Date Formatting

The format_date() helper validates and formats dates:

Troubleshooting

Authentication Errors

If you see authentication errors:

• Verify your Personal Access Token is correct

• Check that the token hasn't expired

• Ensure the token has the necessary scopes

Missing Data

If queries return empty results:

• Verify you're wearing your Oura Ring

• Check that data has synced to the Oura Cloud

• Try a different date range

Docker Build Issues

If Docker build fails:

• Ensure Docker is running

• Check that you have internet connectivity

• Verify Python base image is accessible

Security Notes

• Never commit your .env file or expose your Personal Access Token

• Use AWS Secrets Manager for production deployments

• Rotate your tokens periodically

• Review AWS IAM permissions regularly

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details

Resources

• Oura API Documentation

• Model Context Protocol

• FastMCP Documentation

• AWS Bedrock AgentCore

Support

For issues and questions:

• GitHub Issues: Report a bug or request a feature

• Oura API Support: cloud.ouraring.com/docs

Acknowledgments

• Inspired by the TypeScript implementation at elizabethtrykin/oura-mcp

• Built with FastMCP

• Powered by Oura Ring API v2