my-oura-mcp

Gives Claude, ChatGPT, and Codex access to your Oura Ring data: sleep, readiness, HRV, resting heart rate, activity, SpO₂, stress.

Ask "how did I sleep last week" and your MCP client calls the right tool and gets a summary back — not a wall of JSON:

{
  "metric": "sleep_detail",
  "period": { "start": "2026-07-23", "end": "2026-07-29", "days": 7 },
  "stats": {
    "total_h":    { "mean": 7.1, "min": 5.9, "max": 8.4 },
    "deep_h":     { "mean": 1.3, "min": 0.9, "max": 1.8 },
    "avg_hrv":    { "mean": 42,  "min": 31,  "max": 55, "trend_per_week": 1.8 },
    "efficiency": { "mean": 88,  "min": 82,  "max": 93 }
  }
}

New to MCP? Model Context Protocol lets AI clients reach external data. Install this server, connect it once, then ask about your sleep in plain language. No coding involved.

Works locally in Claude Code and Codex, and remotely in claude.ai and ChatGPT once it is deployed to a server of your own.

Читать по-русски: README.ru.md

Why another one

• Compact by default. Tools return per-day values plus statistics with a trend, not the raw API payload. Raw responses stay one raw=True away. A month of heart-rate data shrinks by more than 10×.
• One codebase, two transports. stdio for local use, streamable-http for remote. A flag apart, not a rewrite.
• Timezone-correct. Oura filters some endpoints by an internal UTC timestamp while returning a local day field, and returns heart-rate timestamps in UTC. Both quietly lose or misplace data outside UTC. This server handles it — see Timezone handling.
• Survives flaky networks. Follows next_token pagination, retries dropped connections with exponential backoff, and turns HTTP status codes into messages that say what to fix.
• Try before authorizing. Oura's sandbox works with no credentials at all.

Quick start

Requires uv. No Oura token needed for this part.

git clone https://github.com/AntVsl/oura_mcp && cd oura_mcp
cp .env.example .env
uv sync

Check that data flows (hits Oura's sandbox, no auth required):

uv run python -m my_oura_mcp.smoke

Connect it locally — the server prints the commands with the absolute path already filled in, and writes nothing itself:

uv run my-oura-mcp install

Then ask your client for an Oura summary. The get_status tool reports which mode the server is in.

Tools

Every data tool takes either days_back or an explicit start_date/end_date pair (YYYY-MM-DD), plus raw to get Oura's untouched response.

Using your own data

The sandbox returns synthetic data. For your own you need an Oura application and a one-time authorization — no review to pass, a fresh application works immediately.

When registering: Redirect URI is http://localhost:8765/callback, matched byte for byte. Scopes are daily, heartrate, tag, spo2, stress, heart_health. Everything else is arbitrary.

Tokens refresh themselves from there. Check with my-oura-mcp auth --status, forget them with auth --logout.

Personal Access Tokens no longer work: Oura stopped issuing them in December 2025.

Refresh tokens are single-use. Each refresh kills the old one, so two instances sharing a token store knock each other out. The symptom is a 400 mentioning single use; the cure is re-running auth and keeping one instance.

Configuration

Everything lives in .env (see .env.example). Secrets never reach git.

Running it

One codebase, two transports: stdio next to a client on this machine, HTTP on a server so the web clients and your phone can reach it.

Locally

uv run my-oura-mcp install prints these with the absolute path already filled in. --scope user makes the server visible from any directory; without it, only from where the command ran. Verify with claude mcp list / codex mcp list.

Nothing is exposed and no network is involved. To debug the transport itself: uv run my-oura-mcp --transport http --port 8000 — no secret needed on loopback.

On a server

This is what makes the server reachable from any device, from Claude.ai and from ChatGPT. Step by step in docs/DEPLOY.md (Russian): how to let traffic in, how to move Oura authorization across, how to connect web clients.

OURA_PUBLIC_URL turns OAuth on: the server becomes its own authorization server with dynamic client registration, restricted to https://claude.ai and https://chatgpt.com. Another client needs its exact origin in OURA_OAUTH_ALLOWED_REDIRECT_ORIGINS; the consent page names the client and its return origin before asking for the secret.

Two ways to expose it, and the choice is not cosmetic. Caddy is simpler, but its certificate lands in Certificate Transparency — a public log revealing that this address hosts a service. A Cloudflare Tunnel opens no inbound ports at all. If a VPN lives on the same host, only the tunnel will do.

Which one

Keep exactly one live instance: Oura's refresh token is single-use, and two servers sharing a token store will knock each other out of authorization.

Timezone handling

Three separate bugs came from Oura's date semantics, all of which lost data silently rather than raising an error. Worth knowing if you build against this API yourself:

• sleep and daily_activity are filtered by an internal UTC timestamp, not by the day field Oura itself returns. At UTC+3 a night that starts after midnight lands in the previous UTC day: asking for 28..28 returns nothing while the record with day=28 plainly exists. The server widens the window and trims by day afterwards. Verified by sweeping every endpoint; the other six behave.
• heartrate returns timestamps in UTC. Grouping by the first ten characters of that string splits a local day in two, pushing 00:00–03:00 local into the previous day — exactly the resting heart rate you care about. Grouping uses OURA_TZ.
• Oura returns several sleep records per day — the night plus naps. Picking an arbitrary one lets a 12-minute nap displace a full night. The record typed long_sleep wins, or the longest one; naps are reported separately as naps_h so their HRV never averages with the night's.

Security