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:

git clone https://github.com/yourusername/oura-mcp-python.git
cd oura-mcp-python

2. Install dependencies:

pip install -r requirements.txt

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

cp .env.example .env
# Edit .env and add your OURA_PERSONAL_ACCESS_TOKEN

4. Run the server:

python server.py

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:

python test_server.py

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:

============================================================
Testing Oura MCP Server
============================================================

Test 1: Getting personal info...
✓ Personal info retrieved
  Preview: {'id': 'xxx', 'age': 30, ...}...

Test 2: Getting daily readiness (last 7 days)...
✓ Daily readiness retrieved
  Date range: 2024-01-10 to 2024-01-17
  Preview: {'data': [{'day': '2024-01-17', 'score': 85, ...}]}...

Test 3: Getting daily sleep (last 7 days)...
✓ Daily sleep retrieved
  Date range: 2024-01-10 to 2024-01-17
  Preview: {'data': [{'day': '2024-01-17', 'score': 82, ...}]}...

============================================================
All tests passed! ✓
============================================================

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

{
  "mcpServers": {
    "oura-ring": {
      "command": "python",
      "args": ["/absolute/path/to/oura-mcp-python/server.py"],
      "env": {
        "OURA_PERSONAL_ACCESS_TOKEN": "YOUR_TOKEN_HERE"
      }
    }
  }
}

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:

export OURA_PERSONAL_ACCESS_TOKEN="your_token_here"
./deploy-bedrock.sh

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:

# Login to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com

# Build image
docker build -t oura-mcp-server .

# Tag and push
docker tag oura-mcp-server:latest YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/oura-mcp-server:latest
docker push YOUR_ACCOUNT_ID.dkr.ecr.us-east-1.amazonaws.com/oura-mcp-server:latest

2. Store secrets in AWS Secrets Manager:

aws secretsmanager create-secret \
    --name oura-mcp-server/token \
    --secret-string '{"OURA_PERSONAL_ACCESS_TOKEN":"your_token_here"}' \
    --region us-east-1

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

oura-mcp-python/
├── server.py              # Main MCP server implementation
├── requirements.txt       # Python dependencies
├── pyproject.toml        # Project metadata and configuration
├── Dockerfile            # Container image for AWS deployment
├── deploy-bedrock.sh     # Automated AWS deployment script
├── bedrock-agent.json    # Bedrock agent configuration
├── .env.example          # Example environment variables
└── README.md            # This file

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

Code Quality

# Format code
black server.py

# Lint code
ruff check server.py

API Reference

OuraClient

The OuraClient class handles authentication and API requests:

client = OuraClient()
data = await client.make_request("daily_sleep", {"start_date": "2024-01-01"})

Date Formatting

The format_date() helper validates and formats dates:

formatted = format_date("2024-01-15")  # Returns "2024-01-15"
formatted = format_date(None)           # Returns date 30 days ago

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