Metadata-Version: 2.5
Name: mcp-oura
Version: 0.4.0
Summary: The Oura v2 API as an MCP server. Paginates, fixes the date range, warns when data is missing.
Project-URL: Repository, https://github.com/proscar87/oura-mcp
Project-URL: Issues, https://github.com/proscar87/oura-mcp/issues
Author: Oscar Pacheco
License: MIT
License-File: LICENSE
Keywords: health,mcp,oura,sleep,wearables
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=7; extra == 'dev'
Description-Content-Type: text/markdown

# oura-mcp

[![PyPI](https://img.shields.io/pypi/v/mcp-oura?label=PyPI)](https://pypi.org/project/mcp-oura/)
[![Glama score](https://glama.ai/mcp/servers/proscar87/oura-mcp/badges/score.svg)](https://glama.ai/mcp/servers/proscar87/oura-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

English | [简体中文](https://github.com/proscar87/oura-mcp/blob/main/README_zh_CN.md) | [한국어](https://github.com/proscar87/oura-mcp/blob/main/README_ko.md) | [Español](https://github.com/proscar87/oura-mcp/blob/main/README_es.md)

<!-- The Glama badge is live, not a screenshot: it renders whatever that
     independent index scores this server at today. A badge that can only go up
     is decoration; one that can drop is evidence. -->

The [Oura](https://ouraring.com) v2 API as an [MCP](https://modelcontextprotocol.io)
server. All 19 collections, six tools, no dependencies beyond the MCP SDK.

### One local day of heart rate is 1,231 samples across 2 pages

A client that doesn't follow Oura's `next_token` returns **1,000 of them — 81%,
looking complete, with nothing saying otherwise.** Measured against the real API
on 9 August 2026, one person, one ring, 24 hours.

**The test to apply to any Oura MCP server, including this one:** does it take
`next_token` — or a `cursor`, or a `limit` — as a tool parameter? If it does,
pagination is the model's job, and a model that forgets to ask again produces a
confident answer off partial data. This server paginates to exhaustion before it
returns, and tells you how many pages it took.

That's one of **four** ways Oura under-delivers without saying so. All four are
measured below, and all four are corrected here.

### Install

Download **`oura-mcp.mcpb`** from the
[latest release](https://github.com/proscar87/oura-mcp/releases/latest) and
double-click it. Claude Desktop does the rest — no terminal, no Python, no Node.
It runs on Oura's official sample data out of the box, and every sample response
says so, so nothing can pass for your own sleep.

Prefer the command line? `uvx --from mcp-oura oura-mcp`.

Prefer no Python on your machine at all?

```
docker run -i --rm -e OURA_SANDBOX=1 ghcr.io/proscar87/oura-mcp
```

`-i` is not optional: an MCP server speaks over stdin and stdout, not over a
port. Without it the container has no stdin, the handshake never arrives, and
the client reports a server that doesn't show up.

In **claude.ai** or **ChatGPT**, in a browser? Those connect by URL, so the
server has to live somewhere public: deploy it as a Worker on your own
Cloudflare account — free, about ten minutes, yours alone. See
[Remote: claude.ai and ChatGPT](#remote-claudeai-and-chatgpt).

---

## The problem, measured

Oura does not return errors when it can't give you what you asked for. It
returns something different, shaped like a correct response. These are the four
we found by measuring against the real API on 9 August 2026:

### 1. Skip the pagination and you get a fraction

```json
{ "data": [ ... ], "next_token": "eyJ0eXAiOi..." }
```

If `next_token` comes back and you don't follow it, you receive the first page
and **nothing warns you**. One local day of `heartrate` — one person, one ring,
24 hours — is **1,231 samples across 2 pages**. A client that doesn't paginate
gets 1,000 of 1,231: 81%, looking complete. A month is ~37,000.

### 2. Asking for a single day returned zero records

`end_date` **does not behave the same across collections**:

| Exclude the last day requested | Include it |
|---|---|
| `daily_activity`, `sleep`, `workout` | `daily_sleep`, `daily_readiness`, `daily_stress`, `daily_spo2`, `daily_resilience`, `daily_cardiovascular_age`, `sleep_time` |

And on top of that, **`workout` filters by UTC date while reporting `day` in
local time**: at `-06:00`, asking for July 16–18 returned records from the 15th
and 16th — *before* the requested start.

Here the range is inclusive on both ends, always. Two extra days are requested
on each side and then trimmed, which is correct whichever way a given collection
behaves — and stays correct when Oura changes it.

### 3. `latest=true` is ignored where it doesn't apply

Only `heartrate` and `ring_battery_level` honor it. In the other seventeen Oura
doesn't error: it **returns the entire collection**. You ask for the latest
record, you get ten, and you believe it's one. Here it's rejected before the
request goes out.

### 4. A field that doesn't exist is silently ignored

`fields=does_not_exist` returns the **complete** record — the projection never
happens — and `fields=score,does_not_exist` applies the good one and drops the
bad one without a word. Here, fields that never appeared are reported under
`ignored_fields`.

**The pattern is always the same:** you ask for one thing, you get another, and
nothing warns you. That's why this package would rather shout than quietly
under-deliver.

## Installation

### Try it with no credentials

```bash
pip install mcp-oura
OURA_SANDBOX=1 oura-mcp --check
```

The sandbox is official — it's in Oura's OpenAPI spec, with 34 mirror routes —
and serves synthetic data without authentication. 18 of the 19 collections work
there: `personal_info` doesn't, which makes sense, since it's the one returning
email, age, weight and height.

This is the right order: first you watch the server work and learn the shape of
the data, then you go get credentials.

### With your own data

**Oura stopped issuing Personal Access Tokens in December 2025.** Existing ones
still work; new ones can't be created. So there are two paths:

**a) OAuth2 — the one that works today.** Register an application at
[cloud.ouraring.com/oauth/applications](https://cloud.ouraring.com/oauth/applications)
with the redirect `http://localhost:9876/callback/` — **the trailing slash is
required**, the portal rejects the other form with `invalid_redirect_uri`.

> **If you registered on `developer.ouraring.com` instead**, your app belongs to
> Oura's newer portal, whose token endpoint is a different one. The legacy
> endpoint rejects those apps on **every** refresh — so the registration works
> exactly once, until the first access token expires, and then fails forever
> with nothing explaining why. This server tries the legacy endpoint and falls
> back to the new one automatically; nothing to configure either way.


```bash
export OURA_CLIENT_ID="…"
export OURA_CLIENT_SECRET="…"
oura-mcp --authorize             # opens the browser, waits for the callback
oura-mcp --authorize --manual    # headless machines: you paste the URL back
```

The token is stored in `~/.config/oura-mcp/credenciales.json` with mode 600 — or
in the system keychain if you happen to have `keyring` installed, which is not a
dependency of this package — and refreshes itself. `oura-mcp --forget` erases
it.

**b) A personal token, if you already had one.**

```bash
export OURA_PAT="your-token"
oura-mcp --check
```

`--check` is the self-check: it reports which credential you're using, which
scopes were granted and how long the access has left, **without returning the
token or a single health value**. It reports the token's length, never the
token. Error messages get copied and pasted into chats and issues; they have no
business carrying anything else.

### Connecting it to Claude Code

With the package installed (`pip install mcp-oura`):

```bash
claude mcp add -s user oura --env OURA_SANDBOX=1 -- oura-mcp
```

Drop `OURA_SANDBOX` once you've run `oura-mcp --authorize`.

**If you use [uv](https://docs.astral.sh/uv/)**, nothing needs to be installed
permanently:

```bash
claude mcp add -s user oura --env OURA_SANDBOX=1 -- uvx --from mcp-oura oura-mcp
```

The `--from` is required because the distribution is named `mcp-oura` and the
executable `oura-mcp`. *(This needs `uv`; without it the command above fails
with "command not found", and `pip install` is the path to take.)*

As a Claude Code plugin:

```bash
claude plugin marketplace add proscar87/oura-mcp
claude plugin install oura@oura-mcp
```

### Connecting it to Claude Desktop

**One click:** download `oura-mcp.mcpb` from the
[releases page](https://github.com/proscar87/oura-mcp/releases) and double-click
it. Claude Desktop installs it — no terminal, no JSON, no Python. It ships with
sample data turned on, so it works before you have any credential at all.

When you want your own data, just ask it for something: it opens Oura's
authorization page through Claude, waits for the callback, and retries what you
asked. No terminal. That works because MCP has a mode for precisely this — URL
elicitation — and the client does the opening.

The one thing Oura still requires is that every application be registered, so you
need a client ID and secret from
[cloud.ouraring.com/oauth/applications](https://cloud.ouraring.com/oauth/applications)
once. That's Oura's rule, not this server's. `oura-mcp --authorize` remains for
terminal users and for clients that can't show a URL.

**Or by hand,** in `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "oura": {
      "command": "/full/path/to/oura-mcp",
      "env": { "OURA_SANDBOX": "1" }
    }
  }
}
```

`which oura-mcp` gives you the full path. Claude Desktop does not inherit your
terminal's `PATH`, so a bare name there fails silently — one of the most common
mistakes when configuring an MCP server.

### Remote: claude.ai and ChatGPT

> **Experimental.** Tested end to end on Cloudflare's real runtime with Oura's
> sample data, and its Oura login against a fake of Oura — but not yet against
> a real deployment, a real Oura account, or claude.ai and ChatGPT completing
> the connection. If you try it, an issue saying how it went helps.

claude.ai reaches a connector from Anthropic's cloud and ChatGPT from OpenAI's,
not from your computer — so a server on your machine is invisible to both.
[`ts/worker`](ts/worker/README.md) is the same server as a Cloudflare Worker
that **you deploy on your own account, for your own Oura account only**. Nobody
runs a shared instance, so your tokens and your data pass through no one else.

It adds three things the local server does not need: its own consent page,
which shows which app is asking and where the result will go; a check, after
Oura's login, that the account is the one you configured — anyone else is
turned away, and with no owner configured nobody gets in; and a single place
where Oura's single-use refresh token is renewed, one request at a time.

Deployment, step by step, and exactly what has and has not been verified:
[ts/worker/README.md](ts/worker/README.md).

## The tools

| | |
|---|---|
| `oura_collections` | All 19, what each one carries and which parameters it takes |
| `oura_query` | One collection in full over a range, paginating to the end |
| `oura_today` | Last night's sleep and today's readiness, with the days before them |
| `oura_compare` | Whether two periods differ by more than the metric's own noise |
| `oura_relate` | Whether two metrics' day-to-day changes move together beyond chance |
| `oura_check` | Self-check that exposes nothing |

**Six, not nineteen.** A server with one tool per collection forces the model
to pick among 19 similar names before knowing what any of them contain. Here the
collection is a parameter and the catalog is consulted when needed.

All six declare themselves read-only, and that isn't a promise: there is no
`POST`, `PUT` or `DELETE` anywhere in the package, and a test reads the source to
keep it that way.

`oura_today` is the only one that exists for convenience rather than for
correctness: "how did I sleep?" needs today's two records plus enough history
to know whether they are unusual, which was four round trips and four chances
to stop early. **It computes nothing** — no average, no delta, no "your HRV is
up 12%". The days come back raw and the comparison happens where the method
can be cited. Across nine years of real data, three out of four changes
between consecutive measurements fall inside the metric's own normal swing, so
a percentage without that context manufactures a signal rather than reporting
one. Its one parameter is `days`, from 1 to 30, defaulting to 7.

### `oura_compare`: the one calculation, with its method

"Did my HRV go up since I stopped drinking?" is the question people actually
bring, and handing over two averages answers it wrongly: daily metrics swing on
their own, and a good night tends to follow a good night, so a textbook
comparison **calls ordinary noise a change about a third of the time**
(measured: 34–38% at the autocorrelation these metrics typically have).

`oura_compare` takes a `metric` — `collection.field`, such as
`daily_readiness.score`, `sleep.average_hrv` or `daily_activity.steps` — and two
periods, `a_start`/`a_end` and `b_start`/`b_end`. It answers with the two means,
the difference, and the **band this metric moves in on its own over periods that
long**, measured from **your own preceding 120 days** and corrected for that
day-to-day dependence. Then one of three verdicts:

- `outside_noise` — the difference is larger than the band. The level differs;
  not why, and not that it will last.
- `within_noise` — it isn't. **This is not "no change"**: with those days, a
  real change smaller than the band would be missed more often than seen, and
  the response says so.
- `cannot_tell` — fewer than 7 days with a value in a period, or fewer than 60
  days of history to measure the band from, or a metric that never varied —
  Oura's sample data is like that. No band is guessed.

The method was chosen by simulation, not before it: with the band estimated
from your history and a t critical value, noise is called a change **at most
about one time in twenty** at every autocorrelation tried, and the test suite
holds it to that. Today is left out, because it is still accumulating. `sleep`
uses each day's longest main sleep, and the response states that rule. Asking
many comparisons and keeping the one that crosses finds a crossing by chance —
the response says that too.

### `oura_relate`: correlation, with the ways it lies taken out

"Do hard training days lower my readiness the next morning?" Correlating two
columns answers it wrongly in two familiar ways: two metrics that both rise on
weekends correlate without touching each other, and so do two that both drift
over months. Measured on unrelated simulated metrics, a plain correlation
called them related **41–93% of the time** with a shared weekly rhythm, and 58%
with a shared trend.

`oura_relate` takes two metrics, `x` and `y`, a range `start`/`end`, and a
`lag` in days (0–7). It removes each weekday's usual level from each metric,
compares only **day-to-day changes** between consecutive days, corrects the
number of pairs for autocorrelation, and returns the correlation with its 95%
interval and the same three verdicts. Every null simulated — weekly rhythms,
random walks, shared trends, 30% of days missing — stays at about 5% (measured
up to 5.2%).

- **Lag is yours to choose, once.** Oura files a night's sleep and the next
  morning's readiness under the day you woke up, so activity on a day meets the
  sleep that followed it at `lag=1`. `first_pair` shows which day met which, so
  a wrong alignment is visible. Trying several lags is several tests, and
  because the method works on changes, a real relation at one lag also shows
  up, reversed, next to it — the response says both.
- **It needs about three months.** Under 20 effective pairs it answers
  `cannot_tell`, and with gaps in the days it needs longer.
- **It measures co-movement, not cause and not direction.** Something else can
  move both, and the response says so every time.

### `oura_query` parameters

| | |
|---|---|
| `collection` | Which of the 19. `oura_collections` lists them |
| `day` | A single day. Shorthand for `start=end=day` |
| `start`, `end` | The range, **inclusive on both ends** |
| `fields` | Only these fields. Oura trims on its side, so less comes down |
| `latest` | The most recent record. `heartrate` and `ring_battery_level` only |
| `format` | `json` or `csv`. Savings vary by collection: 55% on `heartrate`, 10% on `daily_sleep` |

And what the response tells you when something didn't come out clean:
`truncated` with `continue_from` naming the last day reached, `pagination_cycle` if Oura
repeats a token, `ignored_fields`, `discarded_out_of_range`,
`uneven_columns`, `empty` when a query comes back empty, and
`large_response` when what's returned is heavy enough to matter.

Four more say something happened that you'd otherwise never learn:

- **`synthetic`** — this is Oura's sample data, not yours. It rides on every
  response in sample mode, which is how the extension ships, so a model can't
  report made-up numbers as your sleep.
- **`rate_limited`** — Oura refused with a 429 and a retry got through. **The
  data is complete**; the warning is about the *next* query. Oura sends no
  rate-limit headers on successful responses, so being refused is the only
  signal there is that you're near the ceiling.
- **`fields_split`** — `fields` arrived as `"day,score"` instead of
  `["day","score"]` and was split. No Oura field name contains a comma, so
  splitting is unambiguous — but reinterpreting your input silently would be the
  same sin this whole package is about.
- **`cached`** — the answer came from this session's memory instead of from
  Oura. Only ever for a range that closed **before today**, because a day that
  has ended cannot gain records; today is never held, since the ring syncs
  whenever it likes. An empty answer is never held either — nothing tells "no
  data" apart from "the ring hadn't synced yet", and freezing the second would
  turn a temporary gap into a permanent one. It lives in memory and dies with
  the process: **no health data is ever written to disk.**

That last one comes from measuring: **30 days of `daily_activity` is 252,000
characters**, and 87% of it is a single field, `met`, a per-minute MET series.
Asking for three columns with `fields` brings those same 30 days down to 5,000
characters — **99% less**. The server doesn't trim on its own — that would be
under-delivering — but it does say what's heavy and how to ask for less.

*(Parameter names are stable, documented here, and the tool descriptions the
model reads carry the same information. They were Spanish through 0.2.0; the
rename to English landed in 0.3.0 and is recorded in the CHANGELOG as a
breaking change.)*

## What this server does NOT do

**It doesn't analyze beyond `oura_compare` and `oura_relate`.** No trends, no
anomaly detection, no advice — which is exactly where other servers place their
value.

The reason: an average computed in here reaches the model as a number without
its method. Across nine years of real data, **three out of four changes between
two consecutive measurements fall within the metric's own normal oscillation**. A
server that hands over "your HRV is up 12%" without saying how much that metric
swings on its own isn't informing you: it's manufacturing a signal.

`oura_compare` and `oura_relate` exist because they answer that objection
instead of ignoring it: the band comes with the number. Trends don't have a
method here yet that survives the same simulations — a slope over
autocorrelated days is the easiest signal of all to manufacture — so they
aren't here.

Everything else, you get raw. The analysis belongs where the method can be cited — for
instance with [cotejo](https://github.com/proscar87/cotejo), which draws exactly
that distinction for blood biomarkers.

## The 19 collections

**Daily summaries** — `daily_sleep`, `daily_readiness`, `daily_activity`,
`daily_stress`, `daily_spo2`, `daily_resilience`, `daily_cardiovascular_age`,
`vO2_max`

**The detail the scores hide** — `sleep` (stages, HRV, temperature, latency),
`sleep_time`, `workout`, `session`, `rest_mode_period`, `tag`, `enhanced_tag`

**High resolution** — `heartrate`, `ring_battery_level`

**No range** — `personal_info`, `ring_configuration`

Date-range collections use `YYYY-MM-DD`. `heartrate` and `ring_battery_level`
use ISO 8601 with time.

## Other Oura MCP servers

There are several as of August 2026, and it's worth being precise about the
differences. [`benngermin/oura-mcp`](https://github.com/benngermin/oura-mcp)
**paginates properly**, with a resumable cursor.
[`daveremy/oura-mcp`](https://github.com/daveremy/oura-mcp) shipped the
`end_date` fix the same week we did.
[`davidmosiah/oura-mcp`](https://github.com/davidmosiah/oura-mcp) has the most
complete MCP surface. Pagination no longer distinguishes anyone.

What does, as far as we could verify: **`workout`'s UTC skew isn't documented in
any of them**, nor is rejecting `latest` where Oura ignores it, nor warning about
fields that were never applied. And none of them treats not analyzing as a
stated position.

## Privacy Policy

This section exists because the Claude connectors directory requires one. It is
short because there is little to describe: the server runs on your machine and
talks to a single service, the Oura API.

**What is collected.** Nothing, by us. The health data you request goes from the
Oura API to your MCP client and passes through no server of ours, because there
isn't one.

**What is stored, and where.** Only your credentials, and only on your machine:

| | |
|---|---|
| OAuth2 tokens | `~/.config/oura-mcp/credenciales.json`, mode `600` — or the system keychain if you have `keyring` |
| Personal token | Wherever you put it: `OURA_PAT`, or the file `OURA_PAT_FILE` points to |

No health data is written to disk, and that is the constraint the cache was designed around rather than a claim made after the fact. Answers for a day that has already closed are held **in memory only**, for the life of the process, and `--forget` clears them. Nothing about your sleep survives the server exiting.

**If you deploy the remote Worker**, the same holds with one difference: it
runs on *your* Cloudflare account instead of your machine, so that is where your
Oura tokens live — in a Durable Object — and the apps' tokens for it are kept in
KV hashed, with what they carry encrypted. Health data is still never stored:
it is fetched per request and held only in the Worker's memory. No one but you
operates it. Details: [ts/worker/README.md](ts/worker/README.md#what-is-stored-and-where).

**Who it is shared with.** No one. The only outbound connection is to
`api.ouraring.com`, with your token, to fetch what you asked for. Oura's use of
your data is governed by [their privacy
policy](https://ouraring.com/privacy-policy), not by this one.

**How long it is retained.** Credentials, until you delete them:
`oura-mcp --forget`, or by removing the file. Health data isn't retained at all
— it lives in the response and that's it.

**Diagnostics expose nothing.** `oura_check` reports the token's length, never
the token; the profile's field names, never their values. The token is wrapped
in a type that won't print even in a stack trace.

**Contact.** [Repository issues](https://github.com/proscar87/oura-mcp/issues).

## A note on language

The repository is in English: the code, its comments, the tests, and the
internal documents (`AGENTS.md`, `ROADMAP.md`, `CHANGELOG.md`).

It was written in Spanish through 0.2.0. The tool parameters were renamed in
0.3.0 — a breaking change, recorded as one in the CHANGELOG — and the prose
followed. Anything still in Spanish is a storage key that cannot be renamed
without orphaning credentials someone already saved, and there is a test
saying so by name.

## License

MIT.

---

<!-- The MCP registry requires this line in the README of the package published
     to PyPI: it's how it verifies that whoever publishes the server also
     controls the package. Without it, `mcp-publisher publish` returns a 400. -->
mcp-name: io.github.proscar87/oura-mcp
