Oura Ring MCP Server

A comprehensive Model Context Protocol (MCP) server for the Oura Ring API V2. Access sleep, activity, readiness, heart rate, stress, and other health data from your Oura Ring through AI assistants like Claude, ChatGPT, or Cursor IDE.

Security First: This server implements read-only operations only for user data. Your health information cannot be modified.

What is This?

This MCP server allows AI assistants to access your Oura Ring health data. When connected, you can ask questions like:

• "How did I sleep last night?"

• "What's my readiness score this week?"

• "Show me my heart rate trends"

• "Analyze my stress patterns"

Keywords: Oura Ring, MCP Server, Model Context Protocol, Sleep Tracking, Health Data, Wearable API, AI Integration, Claude, ChatGPT, Cursor

Related MCP server: Oura Ring MCP Server

Table of Contents

• What is Oura Ring?

• Features

• Quick Start

• Getting an Access Token

• Configuration

• MCP Client Setup

• Available Tools (37 Total)

• Tool Reference

• For AI Agents

• Rate Limiting

• Project Structure

• Security

• Troubleshooting

• Contributing

• License

What is Oura Ring?

Oura Ring is a smart ring that tracks:

• Sleep - Sleep stages (deep, light, REM), sleep quality, timing

• Activity - Steps, calories, movement throughout the day

• Readiness - Recovery score based on sleep, activity, and body signals

• Heart Rate - Continuous heart rate and HRV (heart rate variability)

• Body Temperature - Skin temperature deviations

• Stress - Daytime stress and recovery patterns

• SpO2 - Blood oxygen saturation levels

This MCP server provides access to all this data through the Oura API V2.

Features

Quick Start

1. Clone and Install

git clone https://github.com/trenerok/oura-mcp-server.git
cd oura-mcp-server
npm install

2. Get OAuth2 Credentials

See Getting an Access Token below.

3. Build

npm run build

4. Configure MCP Client

See MCP Client Setup for Claude Desktop, Cursor IDE, or other clients.

Getting an Access Token

Oura uses OAuth2 for authentication. Personal access tokens were deprecated in December 2025.

Step 1: Create an OAuth2 Application

1. Go to Oura Cloud Applications

2. Click "New Application"

3. Fill in the required fields:

   • Display Name: Your app name (e.g., "My MCP Server")

   • Description: Brief description

   • Website: Your website or GitHub repo URL

   • Privacy Policy: URL (can be your GitHub repo for personal use)

   • Terms of Service: URL (can be your GitHub repo for personal use)

   • Redirect URI: http://localhost:8080/callback

4. Select all the Scopes you want to access

5. Click "Create Application"

6. Copy your Client ID and Client Secret

Step 2: Get Access Token

Use the included helper script:

node scripts/get-token.js YOUR_CLIENT_ID YOUR_CLIENT_SECRET

This will:

1. Open your browser to authorize the application

2. Exchange the authorization code for tokens

3. Display your access token and refresh token

Step 3: Save Your Tokens

Add the tokens to your MCP configuration (see MCP Client Setup).

Configuration

Environment Variables

* Required for user data endpoints ** Required for token refresh and webhook management

Automatic Token Refresh

If you provide OURA_REFRESH_TOKEN, OURA_CLIENT_ID, and OURA_CLIENT_SECRET, the server will automatically refresh your access token when it expires (typically after 24 hours).

MCP Client Setup

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "oura": {
      "command": "node",
      "args": ["/absolute/path/to/oura-mcp-server/dist/index.js"],
      "env": {
        "OURA_ACCESS_TOKEN": "your_access_token",
        "OURA_REFRESH_TOKEN": "your_refresh_token",
        "OURA_CLIENT_ID": "your_client_id",
        "OURA_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Cursor IDE

Add to .cursor/mcp.json in your project directory:

{
  "mcpServers": {
    "oura": {
      "command": "node",
      "args": ["./dist/index.js"],
      "env": {
        "OURA_ACCESS_TOKEN": "your_access_token",
        "OURA_REFRESH_TOKEN": "your_refresh_token",
        "OURA_CLIENT_ID": "your_client_id",
        "OURA_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Other MCP Clients

Use similar configuration with the appropriate config file format for your client.

Available Tools (37 Total)

Overview by Category

Complete Tool List

Personal Info (1 tool)

Sleep (6 tools)

Activity (2 tools)

Health Metrics (14 tools)

Workouts (4 tools)

Tags (4 tools)

Device (4 tools)

Webhooks (6 tools) - Requires Client Credentials

Tool Reference

Common Parameters

Date Range Parameters (most tools)

DateTime Parameters (heart rate only)

Example Responses

Personal Info

{
  "id": "abc123",
  "age": 35,
  "weight": 75.5,
  "height": 1.80,
  "biological_sex": "male",
  "email": "user@example.com"
}

Daily Sleep

{
  "data": [
    {
      "id": "sleep123",
      "day": "2024-01-15",
      "score": 85,
      "contributors": {
        "deep_sleep": 80,
        "efficiency": 90,
        "latency": 85,
        "rem_sleep": 75,
        "restfulness": 82,
        "timing": 95,
        "total_sleep": 88
      },
      "timestamp": "2024-01-15T00:00:00.000+00:00"
    }
  ],
  "next_token": null
}

Daily Readiness

{
  "data": [
    {
      "id": "ready123",
      "day": "2024-01-15",
      "score": 78,
      "contributors": {
        "activity_balance": 85,
        "body_temperature": 100,
        "hrv_balance": 72,
        "previous_day_activity": 80,
        "previous_night": 75,
        "recovery_index": 90,
        "resting_heart_rate": 82,
        "sleep_balance": 70
      },
      "temperature_deviation": 0.1,
      "timestamp": "2024-01-15T00:00:00.000+00:00"
    }
  ],
  "next_token": null
}

Heart Rate

{
  "data": [
    {
      "bpm": 62,
      "source": "awake",
      "timestamp": "2024-01-15T08:30:00+00:00"
    },
    {
      "bpm": 58,
      "source": "rest",
      "timestamp": "2024-01-15T08:35:00+00:00"
    }
  ],
  "next_token": null
}

For AI Agents

This section provides structured guidance for AI agents using this MCP server.

Server Capabilities

• Data Access: Read-only access to all Oura Ring health data

• Authentication: OAuth2 Bearer token with automatic refresh

• Real-time Data: Data is fetched live from Oura API

• Pagination: Large datasets return next_token for pagination

Quick Start for AI Agents

1. Verify connectivity: Call get_personal_info first

2. Use date ranges: Always specify start_date to limit data

3. Handle empty data: Empty arrays mean no data for that period

4. Check null values: Many fields may be null if unavailable

Recommended Workflows

Health Dashboard

1. get_personal_info() → Get user profile
2. get_daily_readiness(start_date: "<7 days ago>") → Weekly readiness trend
3. get_daily_sleep(start_date: "<7 days ago>") → Weekly sleep scores
4. get_daily_activity(start_date: "<7 days ago>") → Weekly activity
5. get_daily_stress(start_date: "<7 days ago>") → Weekly stress patterns

Sleep Analysis

1. get_daily_sleep(start_date: "<30 days ago>") → Monthly sleep scores
2. get_sleep(start_date: "<7 days ago>") → Detailed sleep sessions with stages
3. get_sleep_time(start_date: "<7 days ago>") → Bedtime recommendations

Fitness Assessment

1. get_daily_activity(start_date: "<30 days ago>") → Activity trends
2. get_workouts(start_date: "<30 days ago>") → Workout history
3. get_vo2_max(start_date: "<30 days ago>") → Cardiovascular fitness
4. get_heart_rate(start_datetime: "<today>T00:00:00Z") → Today's heart rate

Stress & Recovery

1. get_daily_stress(start_date: "<7 days ago>") → Stress levels
2. get_daily_resilience(start_date: "<7 days ago>") → Resilience scores
3. get_daily_readiness(start_date: "<7 days ago>") → Recovery status

Key Metrics Explained

Error Handling

Important Notes

• Date Format: Use YYYY-MM-DD for dates

• Datetime Format: Use ISO 8601 for get_heart_rate (e.g., 2024-01-15T00:00:00Z)

• Timezone: Data is returned in user's timezone

• Pagination: If next_token is not null, more data is available

• Null Values: Fields may be null if ring wasn't worn or data unavailable

Rate Limiting

The server implements automatic rate limiting per Oura API documentation.

Project Structure

oura-mcp-server/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── client.ts          # Oura API client with auth & rate limiting
│   ├── rate-limiter.ts    # Token bucket rate limiter
│   ├── types.ts           # TypeScript type definitions
│   └── tools/
│       ├── index.ts       # Tool aggregator
│       ├── personal-info.ts
│       ├── sleep.ts
│       ├── activity.ts
│       ├── health.ts
│       ├── workout.ts
│       ├── tags.ts
│       ├── device.ts
│       └── webhook.ts
├── scripts/
│   └── get-token.js       # OAuth2 token helper
├── dist/                  # Compiled JavaScript
├── package.json
├── tsconfig.json
├── .env.example
├── .gitignore
├── LICENSE
├── CHANGELOG.md
└── README.md

Security

Best Practices

1. Never commit tokens — Use environment variables

2. Use refresh tokens — Enable automatic token renewal

3. Test with sandbox — Set OURA_USE_SANDBOX=true for development

4. Limit scopes — Only request OAuth2 scopes you need

Security Features

• Access tokens sanitized from all error messages

• Read-only API access (cannot modify data)

• Automatic token refresh (no manual token management)

• Rate limiting prevents API abuse

Troubleshooting

Common Issues

Getting Help

1. Check Oura API Documentation

2. Open an issue on GitHub

3. Check MCP Protocol Documentation

Development

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (auto-rebuild)
npm run dev

# Run server
npm start

# Clean build
npm run clean

Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature/my-feature

3. Make changes and test: npm run build

4. Commit: git commit -m "Add my feature"

5. Push: git push origin feature/my-feature

6. Create a Pull Request

API Reference

• Oura API V2 Documentation

• Oura Authentication Guide

• Model Context Protocol

License

MIT License — see LICENSE file.

Disclaimer

This software is provided "as is" without warranty. This project is not affiliated with or endorsed by Oura Health Oy.

Not medical advice. Oura Ring data is for informational purposes only and should not be used for medical diagnosis or treatment.