oura-ring-python-mcp

oura-ring-python-mcp

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

Tool	Returns
get_personal_info	Age, weight, height, biological sex, email
get_daily_sleep	Daily sleep score and contributors
get_sleep_periods	Each night's sleep and naps: stages, efficiency, heart rate, HRV
get_daily_readiness	Daily readiness score, contributors, temperature deviation
get_daily_activity	Daily activity score, steps, calories, time per activity level
get_daily_stress	Daily time in high stress and in recovery
get_daily_spo2	Nightly average SpO2 and breathing disturbance index
get_daily_resilience	Daily resilience level and contributors
get_workouts	Workouts with type, intensity, calories, distance
get_sessions	Meditation, breathing and rest sessions
get_heart_rate	Heart 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.

git clone https://github.com/osjayaprakash/oura-ring-python-mcp.git && cd oura-ring-python-mcp
uv 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):

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.

Variable	Required	Default	Meaning
OURA_CLIENT_ID	yes		Client ID of your Oura API application
OURA_CLIENT_SECRET	yes		Client secret of your Oura API application
OURA_TOKEN_FILE	no	~/.config/oura-ring-mcp/tokens.json (under $XDG_CONFIG_HOME if set)	Where auth saves the tokens and the server reads them
OURA_TIMEZONE	no	the machine's time zone	Your 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_URI	no	http://localhost:47651/callback	Must match a redirect URI of the application exactly
OURA_SCOPES	no	email personal daily heartrate workout session spo2 stress	Scopes 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:

OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... uvx oura-ring-python-mcp auth   # once
uvx 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:

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:

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

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:

uv sync --extra langfuse

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

Variable	Meaning
LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY	Tracing is on only when both are set
LANGFUSE_BASE_URL	Langfuse URL for self-hosted or regional instances (default: Langfuse Cloud)
LANGFUSE_CAPTURE_DATA	true 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

uv sync
uv run pytest            # offline suite
uv run pytest -m live    # hits the real API; needs `auth` first
uv 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:

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