{
  "markdown": "# my-oura-mcp\n\n[![CI](https://github.com/AntVsl/oura_mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/AntVsl/oura_mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)\n\nGives Claude, ChatGPT, and Codex access to your Oura Ring data: sleep,\nreadiness, HRV, resting heart rate, activity, SpO₂, stress.\n\nAsk \"how did I sleep last week\" and your MCP client calls the right tool and\ngets a summary back — not a wall of JSON:\n\n```json\n{\n  \"metric\": \"sleep_detail\",\n  \"period\": { \"start\": \"2026-07-23\", \"end\": \"2026-07-29\", \"days\": 7 },\n  \"stats\": {\n    \"total_h\":    { \"mean\": 7.1, \"min\": 5.9, \"max\": 8.4 },\n    \"deep_h\":     { \"mean\": 1.3, \"min\": 0.9, \"max\": 1.8 },\n    \"avg_hrv\":    { \"mean\": 42,  \"min\": 31,  \"max\": 55, \"trend_per_week\": 1.8 },\n    \"efficiency\": { \"mean\": 88,  \"min\": 82,  \"max\": 93 }\n  }\n}\n```\n\n> **New to MCP?** Model Context Protocol lets AI clients reach external data.\n> Install this server, connect it once, then ask about your sleep in plain\n> language. No coding involved.\n\nWorks locally in Claude Code and Codex, and remotely in claude.ai and ChatGPT\nonce it is deployed to a server of your own.\n\n*Читать по-русски: [README.ru.md](README.ru.md)*\n\n## Why another one\n\n- **Compact by default.** Tools return per-day values plus statistics with a\n  trend, not the raw API payload. Raw responses stay one `raw=True` away.\n  A month of heart-rate data shrinks by more than 10×.\n- **One codebase, two transports.** `stdio` for local use, `streamable-http`\n  for remote. A flag apart, not a rewrite.\n- **Timezone-correct.** Oura filters some endpoints by an internal UTC\n  timestamp while returning a local `day` field, and returns heart-rate\n  timestamps in UTC. Both quietly lose or misplace data outside UTC. This\n  server handles it — see [Timezone handling](#timezone-handling).\n- **Survives flaky networks.** Follows `next_token` pagination, retries\n  dropped connections with exponential backoff, and turns HTTP status codes\n  into messages that say what to fix.\n- **Try before authorizing.** Oura's sandbox works with no credentials at all.\n\n## Quick start\n\nRequires [uv](https://docs.astral.sh/uv/). No Oura token needed for this part.\n\n```bash\ngit clone https://github.com/AntVsl/oura_mcp && cd oura_mcp\ncp .env.example .env\nuv sync\n```\n\nCheck that data flows (hits Oura's sandbox, no auth required):\n\n```bash\nuv run python -m my_oura_mcp.smoke\n```\n\nConnect it locally — the server prints the commands with the absolute path\nalready filled in, and writes nothing itself:\n\n```bash\nuv run my-oura-mcp install\n```\n\nThen ask your client for an Oura summary. The `get_status` tool reports which\nmode the server is in.\n\n## Tools\n\n| Tool | Returns | Default range |\n|---|---|---|\n| `get_daily_summary` | Sleep, readiness and activity scores at once | 7 days |\n| `get_sleep` | Sleep stages, efficiency, HRV, resting HR, breathing, temperature | 7 days |\n| `get_sleep_score` | Daily sleep score only — lighter than `get_sleep` | 7 days |\n| `get_readiness` | Readiness score, HRV balance, temperature deviation | 7 days |\n| `get_activity` | Activity score, steps, calories | 7 days |\n| `get_heartrate` | Per-minute heart rate collapsed to daily stats | 3 days |\n| `get_spo2` | Blood oxygen during sleep, breathing disturbance index | 7 days |\n| `get_stress` | Time under load and in recovery | 7 days |\n| `get_heart_health` | Cardiovascular age, VO₂max | 30 days |\n| `get_tags` | Tags you entered in the Oura app | 30 days |\n| `get_status` | Server mode and authorization state | — |\n\nEvery data tool takes either `days_back` or an explicit `start_date`/`end_date`\npair (`YYYY-MM-DD`), plus `raw` to get Oura's untouched response.\n\n## Using your own data\n\nThe sandbox returns synthetic data. For your own you need an Oura application\nand a one-time authorization — no review to pass, a fresh application works\nimmediately.\n\n| | What to do |\n|---|---|\n| 1 | Register an application at [developer.ouraring.com](https://developer.ouraring.com/applications) |\n| 2 | Put `OURA_CLIENT_ID` and `OURA_CLIENT_SECRET` into `.env` |\n| 3 | `uv run my-oura-mcp auth` — opens a browser, stores tokens with mode `600` |\n| 4 | Set `OURA_API_MODE=production` in `.env` |\n\nWhen registering: **Redirect URI** is `http://localhost:8765/callback`, matched\nbyte for byte. **Scopes** are `daily`, `heartrate`, `tag`, `spo2`, `stress`,\n`heart_health`. Everything else is arbitrary.\n\nTokens refresh themselves from there. Check with `my-oura-mcp auth --status`,\nforget them with `auth --logout`.\n\n> Personal Access Tokens no longer work: Oura stopped issuing them in December\n> 2025.\n>\n> **Refresh tokens are single-use.** Each refresh kills the old one, so two\n> instances sharing a token store knock each other out. The symptom is a `400`\n> mentioning single use; the cure is re-running `auth` and keeping one instance.\n\n## Configuration\n\nEverything lives in `.env` (see `.env.example`). Secrets never reach git.\n\n| Variable | Purpose |\n|---|---|\n| `OURA_CLIENT_ID` / `OURA_CLIENT_SECRET` | Oura application credentials |\n| `OURA_REDIRECT_URI` | Must match the application exactly |\n| `OURA_API_MODE` | `sandbox` (synthetic data) or `production` |\n| `OURA_TZ` | Timezone deciding what \"today\" means. **Set explicitly on servers** |\n| `OURA_MCP_TOKEN` | Shared secret guarding the HTTP endpoint; also the consent-page password |\n| `OURA_PUBLIC_URL` | Public `https` address. When set, enables OAuth for Claude.ai and ChatGPT |\n| `OURA_OAUTH_ALLOWED_REDIRECT_ORIGINS` | Comma-separated OAuth client origins; defaults to Claude.ai and ChatGPT |\n| `OURA_TOKEN_STORE` | Where the OAuth flow writes tokens. Not set by hand |\n| `OURA_CACHE_DB` | SQLite cache file. An empty value disables caching |\n\n## Running it\n\nOne codebase, two transports: `stdio` next to a client on this machine, HTTP on\na server so the web clients and your phone can reach it.\n\n### Locally\n\n| Client | Command |\n|---|---|\n| Claude Code | `claude mcp add --scope user oura -- uv --directory PATH run my-oura-mcp` |\n| Codex | `codex mcp add oura -- uv --directory PATH run my-oura-mcp` |\n\n`uv run my-oura-mcp install` prints these with the absolute path already filled\nin. `--scope user` makes the server visible from any directory; without it, only\nfrom where the command ran. Verify with `claude mcp list` / `codex mcp list`.\n\nNothing is exposed and no network is involved. To debug the transport itself:\n`uv run my-oura-mcp --transport http --port 8000` — no secret needed on loopback.\n\n### On a server\n\nThis is what makes the server reachable from any device, from Claude.ai and from\nChatGPT. Step by step in **[docs/DEPLOY.md](docs/DEPLOY.md)** (Russian): how to\nlet traffic in, how to move Oura authorization across, how to connect web\nclients.\n\n| Client | How it connects |\n|---|---|\n| Claude.ai, ChatGPT | OAuth. No client ID or secret to enter — the client registers itself and the consent page asks for `OURA_MCP_TOKEN` |\n| Claude Code | `claude mcp add --scope user --transport http oura URL --header \"Authorization: Bearer TOKEN\"` |\n| Codex | `codex mcp add oura --url URL --bearer-token-env-var OURA_MCP_TOKEN` |\n\n`OURA_PUBLIC_URL` turns OAuth on: the server becomes its own authorization\nserver with dynamic client registration, restricted to `https://claude.ai` and\n`https://chatgpt.com`. Another client needs its exact origin in\n`OURA_OAUTH_ALLOWED_REDIRECT_ORIGINS`; the consent page names the client and its\nreturn origin before asking for the secret.\n\nTwo ways to expose it, and the choice is not cosmetic. Caddy is simpler, but its\ncertificate lands in Certificate Transparency — a public log revealing that this\naddress hosts a service. A Cloudflare Tunnel opens no inbound ports at all.\n**If a VPN lives on the same host, only the tunnel will do.**\n\n### Which one\n\n| | stdio, local | HTTP, on a server |\n|---|---|---|\n| Claude Code and Codex on this machine | yes | yes |\n| Other devices | no | yes |\n| Claude.ai, ChatGPT, phone | no | yes, over OAuth |\n| Needs a domain and a host | no | yes |\n| Data leaves this machine | no | yes, to your server |\n\nKeep **exactly one live instance**: Oura's refresh token is single-use, and two\nservers sharing a token store will knock each other out of authorization.\n\n## Timezone handling\n\nThree separate bugs came from Oura's date semantics, all of which lost data\nsilently rather than raising an error. Worth knowing if you build against this\nAPI yourself:\n\n- **`sleep` and `daily_activity` are filtered by an internal UTC timestamp**,\n  not by the `day` field Oura itself returns. At UTC+3 a night that starts\n  after midnight lands in the previous UTC day: asking for `28..28` returns\n  nothing while the record with `day=28` plainly exists. The server widens the\n  window and trims by `day` afterwards. Verified by sweeping every endpoint;\n  the other six behave.\n- **`heartrate` returns timestamps in UTC.** Grouping by the first ten\n  characters of that string splits a local day in two, pushing 00:00–03:00\n  local into the previous day — exactly the resting heart rate you care about.\n  Grouping uses `OURA_TZ`.\n- **Oura returns several sleep records per day** — the night plus naps. Picking\n  an arbitrary one lets a 12-minute nap displace a full night. The record typed\n  `long_sleep` wins, or the longest one; naps are reported separately as\n  `naps_h` so their HRV never averages with the night's.\n\n## Security\n\n- `.env`, the token store and the cache are in `.gitignore`. Verify before\n  committing: `git status --porcelain`.\n- The token store and SQLite cache are written with owner-only (`600`) file\n  permissions.\n- The HTTP endpoint is guarded by `OURA_MCP_TOKEN` using a constant-time\n  comparison. The access model is deliberately simple: one secret, one owner,\n  no per-user separation.\n- **The server refuses to start on a non-loopback address without a secret**\n  rather than quietly serving health data to the open internet. Try it:\n  `uv run my-oura-mcp --transport http --host 0.0.0.0`.\n- `/healthz` is intentionally open — a reverse proxy needs it, and it returns\n  nothing but `ok`.\n- Caddy strips the `Authorization` header from its logs.\n\n## Caching\n\nOlder days go into SQLite. The two most recent completed days are rechecked on\nevery request because late syncs can update them; older history is served from\nthe cache without a network call.\n\n```bash\nuv run my-oura-mcp cache --status   # what is cached\nuv run my-oura-mcp cache --clear    # forget it\n```\n\nThree things worth knowing. **Today is never cached** — Oura is still writing\nit. **Empty days are not cached either**: an empty day means either \"did not\nwear the ring\" or \"has not synced yet\", and the second resolves itself within\nhours, whereas a cached blank would last forever. **The mode is part of the\nkey**, so sandbox data cannot surface in production.\n\nPer-minute heart rate bypasses the cache: its rows carry no `day` field.\n\n## MCP resources\n\nClients that support resources can read `oura://today`, `oura://yesterday`,\nand `oura://week`. They provide the same sleep/readiness/activity summaries\nas the tools, without choosing arguments manually.\n\n## Skill with recipes\n\n[skills/oura](skills/oura) ships a Claude-oriented skill — not more tools, but workflows\non top of them: whether sleep is actually improving, whether today can take\nload, what the body was doing on a bad day, whether a change in routine did\nanything. Each is a sequence of calls plus a way to reason about the answer,\nwhich no single tool can express.\n\nInstall it by copying into your client's skills directory:\n\n```bash\ncp -r skills/oura ~/.claude/skills/\n```\n\nThe recipes are checked against the code by tests: a field name that no tool\nreturns fails `uv run pytest` instead of quietly sending the model nowhere.\n\nCodex can also load these repository skills after copying them to its skills\ndirectory:\n\n```bash\nmkdir -p ~/.codex/skills\ncp -R skills/oura skills/oura-mcp-maintenance ~/.codex/skills/\n```\n\n`oura` interprets data through the MCP server. `oura-mcp-maintenance` guides\nsafe changes to this repository and its Claude/ChatGPT/Codex integration.\n\n## When something doesn't work\n\n**Claude says there are no Oura tools.** The server didn't connect. `claude mcp\nlist` shows its state. A common cause is a relative path where a full one is\nrequired — `uv run my-oura-mcp install` prints the command with the right one.\n\n**\"Авторизация не пройдена — токенов нет\".** The server is in `production` mode\nbut has never signed in to Oura. Run `uv run my-oura-mcp auth`; check token state\nwith `uv run my-oura-mcp auth --status`.\n\n**`401` against a server on a VPS.** `OURA_MCP_TOKEN` doesn't match. Header\nvalues are sent verbatim, so the word `Bearer` and the space belong to the value:\n`Bearer abc123`, not `abc123`.\n\n**Data comes back for the wrong day.** `OURA_TZ` isn't set. A server clock is\nalmost always UTC, so \"today\" starts hours off from yours and a night's sleep\nlands in the previous day. Set it explicitly, e.g. `OURA_TZ=Europe/Moscow`.\n\n**\"refresh-токен отвергнут\".** Oura's refresh token is single-use, and this\nhappens when a second instance spent it. Keep exactly one alive: once the VPS is\nup, point local Claude Code at it too. Recover with `my-oura-mcp auth`.\n\n**Requests to `api.ouraring.com` fail** with `SSL_ERROR_SYSCALL` or a timeout.\nUsually not the server: the client retries four times with backoff. If that\ndoesn't help, a VPN generally does.\n\n**claude.ai won't connect to your server.** Check that `OURA_PUBLIC_URL` is set\nand matches the connector URL character for character, including `https://` and\nno trailing slash. The startup banner says whether OAuth came up. Beyond that,\nsee [docs/DEPLOY.md](docs/DEPLOY.md).\n\n**You press Allow on the consent page and nothing happens.** Check the server\nlogs: a `POST /oauth/consent` returning `303` with no `POST /token` after it\nmeans the browser blocked the hop back to claude.ai. That is what an over-strict\n`Content-Security-Policy` looks like — and `curl` cannot reproduce it, since it\ndoes not enforce CSP at all.\n\n**\"Запрос устарел\" / request expired.** Authorization requests live in process\nmemory, so restarting the server invalidates any consent page already open. The\nsecret is not the problem — go back to claude.ai and start the connection again.\n\n## Development\n\n```bash\nuv run pytest\n```\n\nTests never touch the network; Oura's responses are stubbed with `respx`.\nTool tests go through `mcp.call_tool()` rather than calling the functions\ndirectly — some bugs only appear on the real protocol layer, where MCP clients\npass declared defaults as explicit arguments.\n\nFor Codex and other coding agents, repository instructions and a task/review\nstructure live in [AGENTS.md](AGENTS.md) and [docs/agents](docs/agents/README.md).\n\n**x86_64 macOS:** `cryptography` 49+ ships no wheel for this platform and tries\nto build from Rust sources. `pyproject.toml` pins `48.0.0` for it specifically;\nLinux and native arm64 are untouched. This bites Apple Silicon too whenever\nHomebrew lives in `/usr/local` rather than `/opt/homebrew` — check with\n`file $(which python3)`.\n\n**Flaky network:** if requests to `api.ouraring.com` fail with\n`SSL_ERROR_SYSCALL` or time out, it usually isn't the server. The client makes\nfour attempts with backoff; beyond that, try a VPN.\n\nSee [docs/ROADMAP.md](docs/ROADMAP.md) for what's planned and what was\ndeliberately deferred.\n\n## License\n\nMIT\n\n<!--\nOwnership proof for the MCP registry: this token ties the PyPI package to the\nserver name in server.json, and the registry refuses to publish without it.\nKept in a comment because it is machine-facing, not something a reader needs.\nDo not edit by hand — tests/test_packaging.py checks it against server.json.\n\nmcp-name: io.github.AntVsl/oura-mcp\n-->\n",
  "bytes": 15877,
  "sha": "151476b6b0cdd3653f936b351a7e7129b07bc02360c5ec0618457680d93d0792",
  "repo_slug": "antvsl/oura_mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_antvsl_oura_mcp_94c58d61/readme"
}