# 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](https://cloud.ouraring.com/personal-access-tokens))
### Installation
1. Clone this repository:
```bash
git clone https://github.com/yourusername/oura-mcp-python.git
cd oura-mcp-python
```
2. Install dependencies:
```bash
pip install -r requirements.txt
```
3. Create a `.env` file with your Oura credentials:
```bash
cp .env.example .env
# Edit .env and add your OURA_PERSONAL_ACCESS_TOKEN
```
4. Run the server:
```bash
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:
```bash
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`
```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:
```bash
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**:
```bash
# 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**:
```bash
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
```bash
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
```
### Code Quality
```bash
# Format code
black server.py
# Lint code
ruff check server.py
```
## API Reference
### OuraClient
The `OuraClient` class handles authentication and API requests:
```python
client = OuraClient()
data = await client.make_request("daily_sleep", {"start_date": "2024-01-01"})
```
### Date Formatting
The `format_date()` helper validates and formats dates:
```python
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](https://cloud.ouraring.com/docs)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [AWS Bedrock AgentCore](https://aws.amazon.com/bedrock/agents/)
## Support
For issues and questions:
- GitHub Issues: [Report a bug or request a feature](https://github.com/yourusername/oura-mcp-python/issues)
- Oura API Support: [cloud.ouraring.com/docs](https://cloud.ouraring.com/docs)
## Acknowledgments
- Inspired by the TypeScript implementation at [elizabethtrykin/oura-mcp](https://github.com/elizabethtrykin/oura-mcp)
- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Powered by [Oura Ring API v2](https://cloud.ouraring.com/docs)
