Skip to main content
Glama
Sign In
deenesjakoruzh
Oura MCP server

Oura MCP server

by rollecode
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Oura MCP server

Version Python Node OAuth

Read your Oura ring from Claude.ai and Claude Code: sleep with the full periods behind the score, readiness, activity, workouts, heart rate, stress, SpO2, resilience, cardiovascular age, VO2 max, bedtime recommendations, tags and rest mode. It talks to the documented Oura API v2 and puts an OAuth 2.1 login in front so you can add it to Claude.ai as a custom connector. Claude Code can use a plain token instead.

WARNING

Using this server with a paid AI service costs money. Tool definitions and results are billed as input tokens, and an agent can call tools repeatedly on its own. You are responsible for every charge, so set spending limits with your provider. The author accepts no liability for any costs. SeeDISCLAIMER.md.

Why not the npm package

This started as a wrapper around @daveremy/oura-mcp and replaced it, because that package returns nothing for most of what you would ask it. It queries single-day ranges as start_date == end_date, and the Oura API does not answer those the way the naming suggests:

  • sleep filters on bedtime_start in UTC, so a night that begins at 00:31 local (UTC+3) lands on the previous UTC day and falls outside its own day's window

  • daily_activity and workout treat end_date as exclusive, making a same-day range zero-width

The result is silent: oura_sleep returns a score with an empty periods array, oura_activity returns null, and oura_workouts returns [], on every single-day call. Nothing errors, so it reads as "no data recorded" rather than "the query was wrong". This server pads the range on both sides and filters back by each record's own day field, which is timezone-correct, and follows next_token to exhaustion instead of silently returning one page.

Related MCP server: Oura MCP Server

Tools

Tool

What you get

oura_daily_summary

Sleep score, readiness score, sleep periods and activity for a day, in one call

oura_sleep

The daily score with its contributors, plus the raw periods: duration, stages, heart rate, HRV

oura_sleep_time

Oura's recommended bedtime window, and how the actual bedtime compared

oura_readiness

Readiness score and its contributors

oura_resilience

Long-term resilience level, with sleep and daytime recovery contributors

oura_cardiovascular_age

Estimated vascular age and pulse wave velocity

oura_vo2_max

Estimated VO2 max

oura_activity

Score, steps, calories, distance and the activity time breakdown

oura_workouts

Workouts with heart rate, calories, duration and intensity

oura_heart_rate

Continuous heart rate samples for a time window

oura_stress

Daily stress and recovery time

oura_spo2

Average nightly blood oxygen

oura_sessions

Meditation, breathing and relaxation sessions

oura_tags

Tags logged for a day, both the legacy and the enhanced kind

oura_rest_mode

Rest mode periods covering a day

oura_ring

Every ring ever paired, plus battery readings

oura_personal_info

Age, weight, height, biological sex, email

oura_trends

Sleep, readiness, activity and stress scores over a range of days

Every date-scoped tool takes an optional date as YYYY-MM-DD and defaults to today. Oura files a night under the day you woke up.

oura_vo2_max, oura_sleep_time and oura_cardiovascular_age are sparse by design: Oura computes them periodically rather than daily, so an empty result is normal and not a sync failure.

How it fits together

Claude.ai / Claude Code
        |  HTTPS
   Cloudflare Tunnel, or any proxy that gives you HTTPS
        |
   nginx  127.0.0.1:8441
        |
   auth-server.js  :8442    handles the login and the tokens
        |
   oura-mcp  :8440          streamable HTTP, local only
        |
   api.ouraring.com

Ports are 8440-8442 so they sit clear of the other MCPs on this host. The server on :8440 has no login of its own and refuses to bind anywhere but loopback, so it is only ever reached through the login layer.

Setup

Needs Python 3.12 or newer, and Node for the login layer.

python3 -m venv .venv
.venv/bin/pip install -e .
npm install --omit=dev

mkdir -p ~/.config/oura-mcp && chmod 700 ~/.config/oura-mcp
echo "OURA_TOKEN=your-personal-access-token" > ~/.config/oura-mcp/env
chmod 600 ~/.config/oura-mcp/env

CONFIG_DIR=~/.config/oura-mcp node set-password.js 'your-password-here'
openssl rand -hex 32 > ~/.config/oura-mcp/token
chmod 600 ~/.config/oura-mcp/token

Get the Oura token from cloud.ouraring.com.

Then fill in YOUR_USER and the hostname in systemd/*.service and nginx/oura-mcp.conf, and:

sudo cp systemd/*.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now oura-mcp oura-mcp-auth
sudo cp nginx/oura-mcp.conf /etc/nginx/sites-enabled/oura-mcp
sudo nginx -t && sudo systemctl reload nginx

Point a tunnel or an HTTPS proxy at 127.0.0.1:8441. OAuth needs HTTPS.

Check it from outside: discovery should return metadata, and /mcp without a token must return 401.

curl https://your-host/.well-known/oauth-authorization-server
curl -o /dev/null -w '%{http_code}\n' -X POST https://your-host/mcp

Connecting

Claude.ai: Settings, Connectors, Add custom connector, https://your-host/mcp, client ID and secret blank.

Claude Code:

claude mcp add --transport http oura https://your-host/mcp \
  --header "Authorization: Bearer $(cat ~/.config/oura-mcp/token)" --scope user

Running it over stdio instead, without any of the login layer:

OURA_TOKEN=your-token .venv/bin/oura-mcp

Credits

The login layer comes from rollecode/obsidian-remote-mcp.

Available Tools

19 tools
get_result_pageA
Read-onlyIdempotent

Read more of a result that was too large to return in one piece.

Any tool whose answer is too large returns its first page with a paging block. Pass that block's result_id here. Nothing is fetched again: the stored result is paged, filtered and narrowed.

Args: result_id: From the paging block of the earlier answer. offset: First item to return, usually the previous next_offset. limit: At most this many items. Fewer come back if they would not fit. fields: Only these keys of each item. Dots reach nested keys, such as "statistics.sizeOnDisk". The paging.fields list shows what exists. match: Keep only items whose field contains this text, ignoring case, for example {"title": "alien", "year": "1979"}. path: Which list to page when the result holds several, as named in paging.lists. Defaults to the largest.

Inputs: result_id (required), path, limit, match, +2 more. Returns: result

oura_activityA
Read-onlyIdempotent

Get daily activity data (score, steps, calories, distance, activity time breakdown) for a date.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_cardiovascular_ageA
Read-onlyIdempotent

Get estimated vascular age and pulse wave velocity for a date.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_daily_summaryA
Read-onlyIdempotent

Get a one-call overview for a date: sleep score, raw sleep periods, readiness score, and daily activity. Use the more specific tools (oura_sleep, oura_readiness, oura_activity, oura_resilience, etc.) for fields not covered here.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_heart_rateA
Read-onlyIdempotent

Get continuous heart rate samples for a time window. Useful for correlating with untracked activity or workouts.

Args: start_datetime: Start in ISO 8601 (e.g. 2024-01-01T00:00:00+00:00). end_datetime: End in ISO 8601 (e.g. 2024-01-01T23:59:59+00:00).

Inputs: end_datetime (required), start_datetime (required). Returns: result

oura_personal_infoA
Read-onlyIdempotent

Get the account profile: age, weight, height, biological sex, email.

Inputs: no named parameters. Returns: result

oura_readinessA
Read-onlyIdempotent

Get the readiness score and its contributors for a date.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_resilienceA
Read-onlyIdempotent

Get the long-term resilience level (limited/adequate/solid/strong/ exceptional) and its contributors (sleep recovery, daytime recovery, stress) for a date.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_rest_modeA
Read-onlyIdempotent

Get rest mode periods active on a date (Oura's illness/injury/ recovery mode, which relaxes activity goals and readiness contributors).

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_ringA
Read-onlyIdempotent

Get every ring ever paired to the account (model, color, size, firmware) plus battery level readings for a time window (defaults to the last 24 hours).

Args: start_datetime: ISO 8601, defaults to 24 hours ago. end_datetime: ISO 8601, defaults to now.

Inputs: end_datetime, start_datetime. Returns: result

oura_sessionsA
Read-onlyIdempotent

Get guided or unguided meditation, breathing and relaxation sessions for a date.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_sleepA
Read-onlyIdempotent

Get detailed sleep data for a date: the daily sleep score with its contributors, and the raw sleep periods (duration, stages, heart rate, HRV) that score is built from.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_sleep_timeA
Read-onlyIdempotent

Get Oura's recommended bedtime window and how last night's actual bedtime compared to it. Sparse: only populated on days Oura had enough history to compute a recommendation.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_spo2A
Read-onlyIdempotent

Get average nightly blood oxygen (SpO2) percentage for a date.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_stressB
Read-onlyIdempotent

Get daily stress and recovery time for a date.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_tagsA
Read-onlyIdempotent

Get tags logged for a date: built-in and custom tags (e.g. illness, alcohol, travel, a named event), covering both the legacy tag endpoint and the newer enhanced tags with time spans.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_trendsA
Read-onlyIdempotent

Get daily sleep, readiness, activity and stress scores over a range of days, most recent last.

Args: days: Number of days to look back, including today (default 7).

Inputs: days. Returns: result

oura_vo2_maxA
Read-onlyIdempotent

Get the estimated VO2 max for a date. Sparse: Oura only computes this periodically, not every day.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

oura_workoutsA
Read-onlyIdempotent

Get workouts (auto-detected and manually logged) with heart rate, calories, duration and intensity for a date.

Args: date: YYYY-MM-DD, defaults to today.

Inputs: date. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.9/5.0

    Scored across 19 tools

    Disambiguation4/5

    Each tool maps to a distinct Oura data type (sleep, readiness, activity, stress, HR, workouts, etc.), so boundaries are mostly clear. The main overlap is oura_daily_summary, which bundles sleep/readiness/activity that individual tools also expose, but its description explicitly tells agents to use the specific tools for detail.

    Naming Consistency4/5

    All domain tools follow a clean oura_<noun> snake_case pattern, which is highly predictable. The lone exception is get_result_page, which lacks the oura_ prefix, but it is a generic pagination helper rather than a domain endpoint.

    Tool Count4/5

    19 tools is on the heavier side but each corresponds to a genuinely distinct Oura metric or resource, so they each earn their place. The set is neither bloated with redundant tools nor thin for the breadth of the Oura API.

    Completeness4/5

    The surface covers the full range of Oura read endpoints (sleep, readiness, resilience, activity, stress, HR, SpO2, VO2 max, cardiovascular age, tags, sessions, ring, profile, trends) plus paging. It is read-oriented, so write operations like logging tags or workouts are absent, but that matches the API's largely read-only nature.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • Oura MCP Server

      echocharlie
      A
      license
      A
      quality
      C
      maintenance
      Provides read-only access to Oura ring biometrics via the Oura API, enabling Claude to query daily summaries, sleep, readiness, stress, workouts, baselines, and heart rate data. Designed to complement a Strava connector for joint analysis of training and recovery.
      8
      MIT

    • oura-mcp-server

      tommymulder
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude Desktop and Claude Code to access your personal Oura Ring health data—including sleep, readiness, activity, heart rate, and workouts—through local MCP tools.
      8 npm
      MIT