Oura Ring

io.github.osjayaprakashPublished by GitHub account osjayaprakashv0.1.0Updated Oct 27, 2026

Read-only Oura Ring sleep, readiness, activity, stress and heart rate data (OAuth2)

VerifiedSTDIODesktop onlyLocation & LifestyleData & Analytics

Overview

AI-generated overview

Read-only MCP server that lets an assistant query your Oura Ring sleep, readiness, activity, stress, SpO2, workout and heart rate data via the Oura API v2.

What you can do
  • Read personal profile details such as age, weight, height and biological sex
  • Fetch daily scores and contributors for sleep, readiness, activity, stress, SpO2 and resilience
  • Retrieve nightly sleep periods and naps with stages, efficiency, heart rate and HRV
  • List workouts and meditation, breathing or rest sessions
  • Pull heart rate samples with min, max and average bpm over a chosen time window
  • Daily queries default to the last 7 days (max 90); heart rate defaults to the last 24 hours (max 7 days)
When to use it
Useful when you want an assistant to review your Oura metrics, spot trends in sleep or readiness, or summarize activity and stress over a date range without exporting data by hand.
Requirements
Runs locally over stdio via uvx, Docker or a cloned repo with uv. Needs an Oura API application with OURA_CLIENT_ID and OURA_CLIENT_SECRET, a redirect URI of and the listed scopes. A one-time OAuth sign-in saves tokens to a local file; OURA_TIMEZONE and OURA_TOKEN_FILE are optional. Gen3 and Ring 4 users need an active Oura membership.
Before you install
Handles health data (sleep, heart rate, activity) and personal details including email. OURA_CLIENT_SECRET and the saved OAuth tokens are sensitive; keep the token file private. Optional Langfuse tracing sends data to a third-party instance, and LANGFUSE_CAPTURE_DATA=true includes tool inputs and outputs. Access is read-only, but revoking access requires re-running auth.

Installation

In SourceWeft

  1. Open Oura Ring in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

oura-ring-python-mcp

[CI] [PyPI] [Python] [Docker] [License: MIT]

An MCP server that gives Claude (or any MCP client) read-only access to your Oura Ring data: sleep, readiness, activity, stress, SpO2, resilience, workouts, sessions and heart rate. It talks to the Oura API v2 with its own small async client (oura_ring_mcp.core).

Tools

ToolReturns
get_personal_infoAge, weight, height, biological sex, email
get_daily_sleepDaily sleep score and contributors
get_sleep_periodsEach night's sleep and naps: stages, efficiency, heart rate, HRV
get_daily_readinessDaily readiness score, contributors, temperature deviation
get_daily_activityDaily activity score, steps, calories, time per activity level
get_daily_stressDaily time in high stress and in recovery
get_daily_spo2Nightly average SpO2 and breathing disturbance index
get_daily_resilienceDaily resilience level and contributors
get_workoutsWorkouts with type, intensity, calories, distance
get_sessionsMeditation, breathing and rest sessions
get_heart_rateHeart rate samples with min, max and average bpm

Daily tools take optional start_date and end_date (YYYY-MM-DD, both inclusive). Without them they cover the 7 days ending today; ranges are limited to 90 days. Each result echoes the range it covers, so the model always knows what "today" meant.

get_heart_rate takes optional start_datetime and end_datetime (ISO 8601). Without them it covers the last 24 hours; windows are limited to 7 days.

Per-interval series (5-minute activity classes, MET, sleep phases, in-sleep heart rate and HRV curves) are left out of results to keep them small; the scores, totals and averages are kept.

Setup

For a step-by-step guide, including creating the Oura application and troubleshooting, see the installation guide. Full documentation is at https://oura-ring-python-mcp.readthedocs.io.

The server signs in with OAuth2, since Oura has deprecated personal access tokens. You need an Oura API application (a client ID and secret) whose redirect URIs include http://localhost:47651/callback, with the scopes email, personal, daily, heartrate, workout, session, spo2 and stress allowed (resilience needs stress). Gen3 and Oura Ring 4 users need an active Oura membership for the API to return data.

bash
git clone https://github.com/osjayaprakash/oura-ring-python-mcp.git && cd oura-ring-python-mcpuv sync

Sign in once. This opens the browser, catches Oura's redirect on localhost, and saves the tokens to ~/.config/oura-ring-mcp/tokens.json (readable only by you):

bash
OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... uv run oura-ring-python-mcp auth

From then on the server refreshes the access token by itself (Oura issues them for 30 days) and saves each new single-use refresh token. Run auth again only if you revoke access or the saved refresh token is lost.

VariableRequiredDefaultMeaning
OURA_CLIENT_IDyesClient ID of your Oura API application
OURA_CLIENT_SECRETyesClient secret of your Oura API application
OURA_TOKEN_FILEno~/.config/oura-ring-mcp/tokens.json (under $XDG_CONFIG_HOME if set)Where auth saves the tokens and the server reads them
OURA_TIMEZONEnothe machine's time zoneYour IANA time zone, e.g. Europe/London, so "today" matches Oura's days. Set it when running in Docker, where the default is UTC
OURA_REDIRECT_URInohttp://localhost:47651/callbackMust match a redirect URI of the application exactly
OURA_SCOPESnoemail personal daily heartrate workout session spo2 stressScopes to request

If the redirect URI isn't http://localhost:<port>/... (or you're signing in over SSH or in Docker), auth asks you to paste the URL the browser ended up on instead; force that with auth --paste.

Run from PyPI

No clone needed; uv fetches and runs the published package:

bash
OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... uvx oura-ring-python-mcp auth   # onceuvx oura-ring-python-mcp

In a client config, use "command": "uvx", "args": ["oura-ring-python-mcp"].

Run with Docker

Sign in on the host first (above), then mount the token folder so the container can read the tokens and save refreshed ones. The server speaks MCP over stdio, so keep -i:

bash
docker run -i --rm --user "$(id -u):$(id -g)" \  -e OURA_CLIENT_ID -e OURA_CLIENT_SECRET -e OURA_TIMEZONE=Europe/London \  -v ~/.config/oura-ring-mcp:/tokens \  ghcr.io/osjayaprakash/oura-ring-python-mcp:latest

The image reads the tokens from /tokens/tokens.json. --user lets the container read and update your token file on Linux; Docker Desktop on macOS and Windows doesn't need it. To sign in from the container instead, run it with -it and the command auth --paste.

In a client config, use "command": "docker" with those arguments, and pass the variables through the client's env block.

Claude Desktop

Add to claude_desktop_config.json:

json
{  "mcpServers": {    "oura": {      "command": "uv",      "args": ["--directory", "/absolute/path/to/oura-ring-python-mcp", "run", "oura-ring-python-mcp"],      "env": {        "OURA_CLIENT_ID": "your-client-id",        "OURA_CLIENT_SECRET": "your-client-secret"      }    }  }}

Claude Code

bash
claude mcp add oura \  -e OURA_CLIENT_ID=your-client-id \  -e OURA_CLIENT_SECRET=your-client-secret \  -- uv --directory /absolute/path/to/oura-ring-python-mcp run oura-ring-python-mcp

Langfuse tracing (optional)

Each tool call becomes a Langfuse trace, with a child span for each Oura API call. Install the extra and set the keys:

bash
uv sync --extra langfuse

In the server command, use run --extra langfuse oura-ring-python-mcp instead of run oura-ring-python-mcp.

VariableMeaning
LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEYTracing is on only when both are set
LANGFUSE_BASE_URLLangfuse URL for self-hosted or regional instances (default: Langfuse Cloud)
LANGFUSE_CAPTURE_DATAtrue to include tool inputs, outputs and error messages. Default false

Privacy: sleep, heart rate and activity data are health data. By default, traces hold only tool names, timings and error class names. Setting LANGFUSE_CAPTURE_DATA=true sends your data to your Langfuse instance; only do that with an instance you trust, such as a self-hosted one.

Development

bash
uv syncuv run pytest            # offline suiteuv run pytest -m live    # hits the real API; needs `auth` firstuv run ruff check src tests && uv run ruff format --check src tests

Releasing

Bump version in pyproject.toml and both versions in server.json (a test checks they match), commit, then push a tag:

bash
git tag v0.1.0 && git push origin v0.1.0

The tag publishes to PyPI (pypi.yml, needs the PYPI_API_TOKEN secret), to ghcr.io/osjayaprakash/oura-ring-python-mcp (docker.yml), and then to the MCP Registry (mcp-registry.yml).

License

MIT

Source: README.md at commit b9c92a3

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 27, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts