# Oura MCP Server

A Model Context Protocol (MCP) server for Oura Ring health data integration with Claude Desktop. 

## 📋 Prerequisites

Before setting up the Oura MCP Server, ensure you have the following:

### System Requirements
- **Python**: 3.9+ (required for type annotations and modern features)
- **Operating System**: macOS, Linux, or Windows
- **Memory**: Minimum 512MB RAM (1GB+ recommended for advanced analytics)
- **Network**: Internet connection for Oura API access

### Hardware Requirements
- **Oura Ring**
- **Oura Account**

### Software Dependencies
- **Claude Desktop**: Latest version with MCP support
- **Python Package Manager**: `pip` or `uv` (uv recommended for faster installs)

### Required Python Packages
The server depends on several Python packages (automatically installed via requirements.txt):
- `httpx` - Async HTTP client for Oura API
- `structlog` - Structured logging
- `pydantic` - Data validation and serialization
- `numpy` - Numerical computations for analytics
- `scipy` - Statistical analysis and correlation calculations
- `fastmcp` - MCP server framework

### Development Tools (Optional)
- **Code Editor**: VS Code, PyCharm, or similar with Python support
- **Git**: For version control and updates
- **Virtual Environment**: `venv` or `conda` for isolated Python environment

### Oura API Access
- **Personal Access Token**: Required from [Oura Cloud](https://cloud.ouraring.com/personal-access-tokens)
- **Data Permissions**: The token provides access to all your personal health data
- **Rate Limits**: 5000 requests per day (automatically managed by the server)

### Claude Desktop Configuration
- **Config File Access**: Ability to edit `claude_desktop_config.json`
- **Environment Variables**: Capability to set environment variables securely

## 🚀 Quick Start

### 1. Get Your Oura Personal Access Token

1. Visit [https://cloud.ouraring.com/personal-access-tokens](https://cloud.ouraring.com/personal-access-tokens)
2. Log in to your Oura account  
3. Click "Create New Personal Access Token"
4. Copy the generated token (save it securely!)

### 2. Clone and Setup Project

```bash
# Clone the repository (if not already done)
git clone <repository-url>
cd oura-ai

# Verify Python version (should be 3.9+)
python3 --version

# Create virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies (choose one method)
# Method 1: Using uv (faster, recommended)
uv pip install -r requirements.txt

# Method 2: Using standard pip
pip install -r requirements.txt

# Verify installation
python3 -c "import httpx, structlog, pydantic; print('Dependencies installed successfully!')"
```

### 3. Configure Claude Desktop

Edit your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "oura-ai": {
      "command": "python3",
      "args": ["/path/to/oura-ai/mcp_server.py"],
      "env": {
        "OURA_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

**Important**: Replace `/path/to/oura-ai/` with your actual project path.

### 4. Test & Verify Setup

```bash
# Test server syntax and imports
python3 mcp_server.py --help

# Test with your Oura token (replace with your actual token)
OURA_PERSONAL_ACCESS_TOKEN=your_actual_token_here python3 mcp_server.py

# You should see output like:
# [INFO] Initializing Oura MCP Server with modular architecture
# [INFO] Starting Oura MCP Server
# [INFO] Features: 18 Resources, 20 Tools, 6 Prompts
# [INFO] Advanced Analytics: Correlations, Anomaly Detection, Trend Prediction
# [INFO] MCP Protocol: 2025-06-18 compatible

# Stop the test server (Ctrl+C) and restart Claude Desktop
```


## ✨ Features

### 📊 **18 MCP Resources** (Default: Last 7 Days)
- **Core Health**: `oura://personal_info`, `oura://daily_sleep`, `oura://daily_activity`, `oura://daily_readiness`  
- **Detailed Data**: `oura://sleep`, `oura://sleep_time`, `oura://heart_rate`
- **Fitness**: `oura://workout`, `oura://session`
- **Advanced Metrics**: `oura://daily_spo2`, `oura://daily_stress`, `oura://daily_resilience`
- **Performance**: `oura://vO2_max`, `oura://daily_cardiovascular_age`
- **Configuration**: `oura://ring_configuration`, `oura://rest_mode_period`
- **Tags**: `oura://tags`, `oura://enhanced_tags`

### 🛠️ **20 MCP Tools**

**🔄 Standard Data Tools:**
- **Core Data**: `get_daily_sleep`, `get_daily_activity`, `get_daily_readiness`, `get_personal_info`
- **Detailed Data**: `get_sleep`, `get_heart_rate`, `get_workout`, `get_session`
- **Advanced Metrics**: `get_daily_spo2`, `get_vO2_max`, `get_tags`, `get_enhanced_tags`
- **Trend Analysis**: `analyze_health_trends`, `analyze_lifestyle_correlations`

**🧬 Advanced Analytics**:
- **`analyze_metric_correlations`**: Statistical correlation analysis between any health metrics
- **`detect_health_anomalies`**: AI-powered anomaly detection with customizable sensitivity
- **`predict_health_trends`**: Machine learning-based health forecasting and predictions
- **`analyze_circadian_rhythm`**: Comprehensive sleep timing and consistency analysis
- **`calculate_stress_resilience`**: Advanced stress resilience and recovery capacity scoring
- **`optimize_workout_timing`**: Performance-based workout timing recommendations
- **`generate_health_visualization_data`**: Structured data for creating health charts and graphs

### 💬 **6 Smart Prompts** (Template-Based)
- **`health_summary`**: Comprehensive health overview prompts
- **`sleep_analysis`**: Detailed sleep optimization prompts  
- **`activity_coaching`**: Personalized fitness guidance prompts
- **`recovery_insights`**: Recovery optimization prompts
- **`health_goals_tracker`**: Goal tracking and progress prompts
- **`lifestyle_analysis`**: Advanced lifestyle pattern analysis prompts

## 🔥 Advanced Analytics Prompts

Try these powerful prompts with Claude Desktop to unlock advanced health insights:

### 1. **Sleep Quality Deep Dive**
```
Analyze my sleep patterns over the past 2 weeks using analyze_circadian_rhythm and detect_health_anomalies. Find correlations between sleep timing consistency and sleep quality scores. What specific changes should I make to optimize my sleep?
```

### 2. **Performance Optimization Analysis**
```
Use analyze_metric_correlations to find relationships between my readiness scores, HRV, and workout performance over the past month. Then use optimize_workout_timing to recommend the best times for high-intensity training.
```

### 3. **Health Trend Forecasting**
```
Apply predict_health_trends to my sleep, activity, and readiness scores from the last 30 days. What patterns do you see emerging? Predict my health trajectory for the next 2 weeks with actionable recommendations.
```

### 4. **Stress Resilience Assessment** 
```
Calculate my stress resilience using calculate_stress_resilience and analyze correlations between stress indicators (HRV, sleep quality, recovery time) and my daily activities. How can I build better resilience?
```

### 5. **Comprehensive Health Anomaly Detection**
```
Run detect_health_anomalies on all my key metrics (sleep score, activity score, readiness, HRV) over the past 3 weeks. Identify unusual patterns and correlate them with my lifestyle tags. What triggered these anomalies?
```

### 6. **Circadian Rhythm Optimization**
```
Use analyze_circadian_rhythm to assess my sleep timing consistency and correlate it with my daily energy levels and performance metrics. Design a personalized circadian optimization plan.
```

### 7. **Activity-Recovery Balance Analysis**
```
Analyze correlations between my workout intensity, recovery time, and readiness scores. Use the insights to optimize my training schedule and recovery protocols for peak performance.
```

### 8. **Lifestyle Impact Assessment**
```
Correlate my enhanced_tags data with sleep quality, stress levels, and recovery metrics. Which lifestyle factors (alcohol, late meals, travel, stress) have the biggest impact on my health metrics?
```

### 9. **Personalized Health Visualization**
```
Generate comprehensive visualization data for my key health metrics over the past month. Create charts showing trends, correlations, and patterns. What story does my health data tell?
```

### 10. **Holistic Health Optimization Plan**
```
Combine insights from all advanced analytics tools to create a personalized health optimization plan. Analyze my sleep, activity, recovery, and lifestyle patterns to recommend specific, actionable changes for the next 30 days.
```

## Development

```bash
# Test the server locally
OURA_PERSONAL_ACCESS_TOKEN=your_token python3 mcp_server.py

# Install dependencies with uv (faster)
uv pip install -r requirements.txt

# Alternative: traditional pip
pip install -r requirements.txt
```