Skip to main content
Glama
oura-mcp-server

oura-mcp-server

by trenerok

Oura Ring MCP Server

License: MIT Node.js MCP

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?

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

Feature

Description

37 MCP Tools

Complete coverage of all Oura API V2 endpoints

Read-only by design

Cannot modify user data

OAuth2 Authentication

Secure token-based authentication with refresh token support

Automatic Token Refresh

Automatically refreshes expired access tokens

Sandbox Support

Test with mock data before using real data

Rate Limiting

Built-in rate limiting with exponential backoff

Token Sanitization

Access tokens are never exposed in logs or errors


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

Variable

Required

Description

OURA_ACCESS_TOKEN

Yes*

OAuth2 access token for user data

OURA_REFRESH_TOKEN

No

Refresh token for automatic token renewal

OURA_CLIENT_ID

No**

OAuth2 application client ID

OURA_CLIENT_SECRET

No**

OAuth2 application client secret

OURA_USE_SANDBOX

No

Set to true for sandbox/mock data

* 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

Category

Count

Tools

Personal Info

1

User profile (age, weight, height)

Sleep

6

Sleep sessions, daily scores, bedtime recommendations

Activity

2

Daily activity, steps, calories burned

Health Metrics

14

Heart rate, readiness, SpO2, stress, resilience, cardiovascular age, VO2 max

Workouts

4

Workout sessions, meditation/breathing sessions

Tags

4

User-created tags and enhanced tags

Device

4

Ring configuration, rest mode periods

Webhooks

6

Webhook subscription management

Complete Tool List

Personal Info (1 tool)

Tool

Description

get_personal_info

Get user profile: age, weight, height, biological sex, email

Sleep (6 tools)

Tool

Description

get_sleep

Detailed sleep sessions with stages (deep, light, REM), HRV, heart rate

get_sleep_by_id

Single sleep session by document ID

get_daily_sleep

Daily sleep scores with contributor breakdown

get_daily_sleep_by_id

Single daily sleep document by ID

get_sleep_time

Optimal bedtime recommendations

get_sleep_time_by_id

Single sleep time document by ID

Activity (2 tools)

Tool

Description

get_daily_activity

Daily steps, calories, active time, MET minutes

get_daily_activity_by_id

Single daily activity document by ID

Health Metrics (14 tools)

Tool

Description

get_heart_rate

Heart rate time series (BPM with timestamps)

get_daily_readiness

Daily readiness scores with contributors

get_daily_readiness_by_id

Single readiness document by ID

get_daily_spo2

Blood oxygen saturation (SpO2) data

get_daily_spo2_by_id

Single SpO2 document by ID

get_daily_stress

Daily stress levels and recovery time

get_daily_stress_by_id

Single stress document by ID

get_daily_resilience

Daily resilience scores

get_daily_resilience_by_id

Single resilience document by ID

get_daily_cardiovascular_age

Vascular age estimates

get_daily_cardiovascular_age_by_id

Single cardiovascular age document by ID

get_vo2_max

VO2 max estimates (cardiovascular fitness)

get_vo2_max_by_id

Single VO2 max document by ID

Workouts (4 tools)

Tool

Description

get_workouts

Workout sessions (activity type, calories, distance, duration)

get_workout_by_id

Single workout document by ID

get_sessions

Meditation and breathing sessions with HRV data

get_session_by_id

Single session document by ID

Tags (4 tools)

Tool

Description

get_tags

User-created tags for tracking behaviors

get_tag_by_id

Single tag document by ID

get_enhanced_tags

Enhanced tags with metadata and time ranges

get_enhanced_tag_by_id

Single enhanced tag document by ID

Device (4 tools)

Tool

Description

get_ring_configuration

Ring details: color, size, firmware, hardware type

get_ring_configuration_by_id

Single ring configuration by ID

get_rest_mode_periods

Rest mode activation history

get_rest_mode_period_by_id

Single rest mode period by ID

Webhooks (6 tools) - Requires Client Credentials

Tool

Description

list_webhook_subscriptions

List all webhook subscriptions

get_webhook_subscription

Get a specific webhook by ID

create_webhook_subscription

Create new webhook subscription

update_webhook_subscription

Update existing webhook

delete_webhook_subscription

Delete a webhook subscription

renew_webhook_subscription

Renew webhook before expiration


Tool Reference

Common Parameters

Date Range Parameters (most tools)

Parameter

Format

Required

Description

start_date

YYYY-MM-DD

No

Start of date range

end_date

YYYY-MM-DD

No

End of date range

next_token

string

No

Pagination token for next page

DateTime Parameters (heart rate only)

Parameter

Format

Required

Description

start_datetime

ISO 8601

No

Start datetime (e.g., 2024-01-01T00:00:00Z)

end_datetime

ISO 8601

No

End datetime

next_token

string

No

Pagination token

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

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

Metric

Range

Meaning

Sleep Score

0-100

Overall sleep quality (>85 = optimal)

Readiness Score

0-100

Recovery level (>85 = ready for activity)

Activity Score

0-100

Daily movement goal progress

Stress (high)

seconds

Time in high stress state

Recovery (high)

seconds

Time in recovery/rest state

HRV

ms

Heart rate variability (higher = better recovery)

Resting HR

bpm

Resting heart rate (lower = better fitness)

Error Handling

Error

Cause

Solution

Access token not configured

Missing OURA_ACCESS_TOKEN

Add token to config

401 Unauthorized

Token expired

Server auto-refreshes if refresh token provided

403 Forbidden

Scope not authorized

Re-authorize with required scopes

429 Rate Limit

Too many requests

Server auto-retries with backoff

Empty data: []

No data for date range

Try different date range

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.

Limit

Value

Requests

5000 per 5 minutes

Algorithm

Token bucket with refill

Retry

Exponential backoff (1s → 2s → 4s, max 30s)

Max Retries

3 attempts


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

Issue

Solution

Cannot find module

Run npm run build

Access token not configured

Add OURA_ACCESS_TOKEN to env

401 Unauthorized

Token expired; add refresh token or get new token

403 Forbidden

Missing OAuth2 scope; re-authorize app

Empty data returned

Check date range; ensure ring synced data

Token not authorized for scope

Re-create OAuth2 app with required scopes

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


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.

Available Tools

40 tools
create_webhook_subscriptionB

Create a new webhook subscription to receive notifications when data changes. Requires OURA_CLIENT_ID and OURA_CLIENT_SECRET environment variables. Valid data types: tag, enhanced_tag, workout, session, daily_activity, daily_sleep, daily_spo2, daily_readiness, sleep, sleep_time, rest_mode_period, ring_configuration, daily_stress, daily_resilience, daily_cardiovascular_age, vO2_max, heartrate.

Inputs: data_type (required), event_type (required), callback_url (required), verification_token (required).

delete_webhook_subscriptionA

Delete a webhook subscription. Requires OURA_CLIENT_ID and OURA_CLIENT_SECRET environment variables.

Inputs: id (required).

get_daily_activityC

Get daily activity data including steps, calories, activity levels, and MET data. Returns activity score with contributors like meeting daily targets, movement frequency, recovery time, and training metrics.

Inputs: end_date, next_token, start_date.

get_daily_activity_by_idB

Get a single daily activity document by its unique ID.

Inputs: document_id (required).

get_daily_cardiovascular_ageC

Get daily cardiovascular age data. Returns vascular age estimates based on physiological measurements.

Inputs: end_date, next_token, start_date.

get_daily_cardiovascular_age_by_idC

Get a single daily cardiovascular age document by its unique ID.

Inputs: document_id (required).

get_daily_readinessC

Get daily readiness scores with contributor breakdown. Returns readiness score with contributors like activity balance, body temperature, HRV balance, recovery index, and sleep metrics.

Inputs: end_date, next_token, start_date.

get_daily_readiness_by_idB

Get a single daily readiness document by its unique ID.

Inputs: document_id (required).

get_daily_resilienceB

Get daily resilience data. Returns resilience level and contributors like sleep recovery, daytime recovery, and stress.

Inputs: end_date, next_token, start_date.

get_daily_resilience_by_idB

Get a single daily resilience document by its unique ID.

Inputs: document_id (required).

get_daily_sleepC

Get daily sleep scores and contributor breakdown. Returns sleep score with contributors like deep sleep, efficiency, latency, REM sleep, restfulness, timing, and total sleep.

Inputs: end_date, next_token, start_date.

get_daily_sleep_by_idB

Get a single daily sleep document by its unique ID.

Inputs: document_id (required).

get_daily_spo2C

Get daily blood oxygen saturation (SpO2) data. Returns average SpO2 percentage readings.

Inputs: end_date, next_token, start_date.

get_daily_spo2_by_idB

Get a single daily SpO2 document by its unique ID.

Inputs: document_id (required).

get_daily_stressC

Get daily stress data. Returns stress levels including high stress time, recovery time, and day summary.

Inputs: end_date, next_token, start_date.

get_daily_stress_by_idB

Get a single daily stress document by its unique ID.

Inputs: document_id (required).

get_enhanced_tag_by_idC

Get a single enhanced tag document by its unique ID.

Inputs: document_id (required).

get_enhanced_tagsC

Get enhanced tags with additional metadata. Returns tags with type codes, time ranges, and comments.

Inputs: end_date, next_token, start_date.

get_heart_rateB

Get heart rate time series data. Returns heart rate readings (BPM) with timestamps and source information. Uses datetime range parameters instead of date range.

Inputs: next_token, end_datetime, start_datetime.

get_personal_infoA

Get personal information for the authenticated Oura user. Returns age, weight, height, biological sex, and email (if available).

Inputs: no named parameters.

get_rest_mode_period_by_idA

Get a single rest mode period document by its unique ID.

Inputs: document_id (required).

get_rest_mode_periodsC

Get rest mode period data. Returns information about when rest mode was activated, including episodes and tags.

Inputs: end_date, next_token, start_date.

get_ring_configurationC

Get Oura Ring configuration details including color, design, size, firmware version, and hardware type. Returns information about the user's ring setup.

Inputs: end_date, next_token, start_date.

get_ring_configuration_by_idA

Get a single ring configuration document by its unique ID.

Inputs: document_id (required).

get_session_by_idB

Get a single session document by its unique ID.

Inputs: document_id (required).

get_sessionsC

Get session data for activities like meditation, breathing exercises, and relaxation. Returns session details including heart rate, HRV, and mood data.

Inputs: end_date, next_token, start_date.

get_sleepC

Get detailed sleep data including sleep stages, heart rate, HRV, and breathing rate. Returns comprehensive sleep session data with durations for deep, light, REM sleep, and more.

Inputs: end_date, next_token, start_date.

get_sleep_by_idB

Get a single sleep document by its unique ID.

Inputs: document_id (required).

get_sleep_timeC

Get optimal bedtime recommendations and sleep timing data. Returns optimal bedtime windows and sleep timing recommendations.

Inputs: end_date, next_token, start_date.

get_sleep_time_by_idB

Get a single sleep time document by its unique ID.

Inputs: document_id (required).

get_tag_by_idB

Get a single tag document by its unique ID.

Inputs: document_id (required).

get_tagsC

Get user-created tags for tracking various activities, behaviors, or conditions. Returns tag text, timestamp, and associated tag categories.

Inputs: end_date, next_token, start_date.

get_vo2_maxC

Get VO2 max estimates. Returns VO2 max values which indicate cardiovascular fitness level.

Inputs: end_date, next_token, start_date.

get_vo2_max_by_idC

Get a single VO2 max document by its unique ID.

Inputs: document_id (required).

get_webhook_subscriptionA

Get details of a specific webhook subscription by ID. Requires OURA_CLIENT_ID and OURA_CLIENT_SECRET environment variables.

Inputs: id (required).

get_workout_by_idC

Get a single workout document by its unique ID.

Inputs: document_id (required).

get_workoutsC

Get workout data including activity type, duration, calories burned, and distance. Returns details about recorded workouts with start/end times and intensity levels.

Inputs: end_date, next_token, start_date.

list_webhook_subscriptionsA

List all webhook subscriptions for your application. Requires OURA_CLIENT_ID and OURA_CLIENT_SECRET environment variables.

Inputs: no named parameters.

renew_webhook_subscriptionA

Renew a webhook subscription to extend its expiration time. Webhook subscriptions expire after some time and need to be renewed. Requires OURA_CLIENT_ID and OURA_CLIENT_SECRET environment variables.

Inputs: id (required).

update_webhook_subscriptionC

Update an existing webhook subscription. Requires OURA_CLIENT_ID and OURA_CLIENT_SECRET environment variables.

Inputs: id (required), data_type, event_type, callback_url, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 40 tools

    Disambiguation4/5

    Tools are mostly distinct: each data type typically has a list and a by_id variant, and descriptions clarify the difference. However, some pairs like get_sleep vs get_daily_sleep or get_tags vs get_enhanced_tags require careful reading, which could cause occasional misselection.

    Naming Consistency4/5

    Consistent snake_case with a get_ / get_..._by_id pattern for most data tools, and list_/get_/create_/update_/delete_ for webhooks. Minor inconsistency: list operations sometimes use singular nouns (get_sleep) and sometimes plural (get_workouts), and get_rest_mode_periods pairs with a singular by_id tool.

    Tool Count2/5

    40 tools is heavy for the apparent scope; many are thin list/by_id pairs that could be merged or parameterized. While each maps to an API endpoint, the count feels excessive and increases cognitive load.

    Completeness5/5

    Covers the full Oura v2 API surface: personal info, all health metrics with list and by_id, workouts, sessions, tags, enhanced tags, ring config, and full webhook CRUD plus renew. No obvious missing endpoints for the domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that provides access to Oura Ring health and fitness data through the Oura API v2, enabling retrieval of sleep, activity, readiness, and other health metrics.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Python-based Model Context Protocol server that provides AI assistants with access to Oura Ring health and fitness data across 15+ endpoints. It enables querying metrics like sleep, activity, readiness, and cardiovascular health through simple authentication and date-range filtering.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides access to Oura Ring health data, including sleep, activity, readiness, and stress metrics via the Model Context Protocol. It enables users to query their personal biometric information and daily health summaries through natural language in MCP-compatible clients.
      ISC
    • A
      license
      B
      quality
      B
      maintenance
      Local-first MCP server that connects AI agents to your Oura Ring readiness, sleep, activity, and HRV data. Tokens never leave your machine.
      27
      175 npm
      6
      MIT