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 stagesget_sleep_sessions- Detailed sleep sessions with heart rate, HRV, and movementget_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 levelsget_workouts- Workout sessions with activity type, duration, and intensityget_sessions- Meditation, breathing exercises, and other sessions
Health Metrics
get_daily_spo2- Blood oxygen saturation levelsget_daily_stress- Stress levels and recovery statusget_daily_resilience- Resilience scores and trendsget_daily_cardiovascular_age- Cardiovascular age estimatesget_vo2_max- VO2 max measurements and trends
Device & Profile
get_ring_configuration- Ring hardware configurationget_rest_mode_period- Rest mode periodsget_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
- Clone this repository:
git clone https://github.com/yourusername/oura-mcp-python.git
cd oura-mcp-python
- Install dependencies:
pip install -r requirements.txt
- Create a
.envfile with your Oura credentials:
cp .env.example .env
# Edit .env and add your OURA_PERSONAL_ACCESS_TOKEN
- 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_TOKENis 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:
- Create an ECR repository
- Build and push the Docker image
- Set up IAM roles for Bedrock
- Store your Oura token in AWS Secrets Manager
- Provide instructions for creating the Bedrock Agent
Manual Deployment Steps
If you prefer manual deployment:
- 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
- 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
- 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
.envfile 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:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
License
MIT License - see LICENSE file for details
Resources
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