hemantkamalakar/oura-mcp-server

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
• 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
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

# 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:

{
  "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

# 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

# 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