\n Give your AI agent your Oura readiness, sleep, activity and HRV — without copy-pasting from the Oura app. \n Local-first MCP server — tokens never leave your machine.\n
\n\n
\n \n \n \n \n
\n\n
\n \n \n \n \n
\n\n> ⚡ **One-command install** with [Delx Wellness for Hermes](https://github.com/davidmosiah/delx-wellness-hermes):\n> `npx -y delx-wellness-hermes setup` — preconfigures this connector and the other 8 in a dedicated Hermes profile.\n>\n> Or wire it standalone into Claude Desktop / Cursor / ChatGPT Desktop — see the install section below.\n\n---\n\n## HTTP (v2 stateless)\n\nDefault is **stdio**. Optional Streamable HTTP — no session id, JSON responses, loopback only:\n\n```bash\nnpx -y oura-mcp-unofficial --http\n# GET http://127.0.0.1:3000/health\n# POST http://127.0.0.1:3000/mcp (sessionless)\n```\n\nEnv: `OURA_MCP_HOST`, `OURA_MCP_PORT`, `OURA_MCP_TRANSPORT=http`.\n\n\n\n\n**Local-first MCP server that connects AI agents to your Oura Ring readiness, sleep, activity and HRV data.**\n\n> **Unofficial project.** Not affiliated with, endorsed by or supported by Ōura Health Oy. Oura is a trademark of its respective owner. Use this only with your own Oura account and in line with the Oura Cloud API terms.\n\nBuilt by [David Mosiah](https://github.com/davidmosiah) for people who use Claude, Cursor, Hermes, OpenClaw or other MCP-compatible agents to think about readiness, sleep and recovery — without copy-pasting numbers from the Oura app.\n\nPart of [Delx Wellness](https://github.com/davidmosiah/delx-wellness), a registry of local-first wellness MCP connectors.\n\n> If this connector helps your agent workflow, please star the repo. Stars make the project easier for other AI builders to discover and help Delx keep shipping local-first wellness infrastructure.\n\n## Why this exists\n\nOura Ring produces some of the most refined personal health signals — readiness scores, sleep stages, HRV, daily activity, SpO2, body temperature trends. But it lives behind an OAuth API with per-scope authorization, and the data is split across multiple endpoints (daily readiness vs. detailed sleep periods vs. heart-rate streams).\n\nThis package handles the OAuth dance locally, normalizes responses across endpoints, and exposes Oura through the Model Context Protocol. Tokens never leave your machine. Privacy-mode defaults keep raw payloads opt-in.\n\n## Setup in 60 seconds\n\nYou'll need an Oura app ([create one here](https://cloud.ouraring.com/oauth/applications)) with redirect URI `http://127.0.0.1:3000/callback`.\n\n```bash\nnpx -y oura-mcp-unofficial setup # interactive: paste client id + secret\nnpx -y oura-mcp-unofficial auth # opens browser, captures the OAuth code\nnpx -y oura-mcp-unofficial doctor # verifies you're ready\n```\n\nRecommended scopes:\n\n```text\ndaily heartrate personal workout spo2\n```\n\nThen add this to your MCP client config:\n\n```json\n{\n \"mcpServers\": {\n \"oura\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"oura-mcp-unofficial\"]\n }\n }\n}\n```\n\nFor Claude Desktop, run `setup --client claude` and the snippet is written for you.\n\n## Quickstart: see the data before you connect\n\nNo Oura account yet? Call `oura_demo` to get realistic example payloads for the\nreadiness, sleep and daily-summary tools, so your agent learns the data contract\nbefore any OAuth setup. All values are synthetic and tagged `is_demo: true`.\n\n```text\nCall oura_demo and show me what the readiness and sleep data looks like.\n```\n\nReal output from `oura_demo` (`response_format=json`, dates are relative to today):\n\n```jsonc\n{\n \"ok\": true,\n \"is_demo\": true,\n \"sample\": {\n \"oura_daily_summary\": {\n \"date\": \"2026-05-29\",\n \"readiness\": { \"score\": 78, \"temperature_deviation\": -0.1, \"hrv_balance\": 84 },\n \"sleep\": { \"score\": 82, \"efficiency\": 89, \"duration_min\": 451, \"deep_min\": 92, \"rem_min\": 108 },\n \"activity\": { \"score\": 86, \"steps\": 9420, \"active_calories\": 412, \"target_calories\": 500 },\n \"spo2\": { \"average\": 96.8 }\n },\n \"oura_wellness_context\": {\n \"window\": \"last_24h\",\n \"readiness_score\": 78,\n \"readiness_band\": \"good\",\n \"sleep_score\": 82,\n \"sleep_efficiency\": 89,\n \"hrv_balance\": 84,\n \"recommendation\": \"Solid readiness and efficient sleep — green light for moderate-to-high intensity. A protein-forward breakfast keeps HRV trending up.\"\n },\n \"oura_list_daily_readiness\": {\n \"count\": 3,\n \"records\": [\n { \"day\": \"2026-05-29\", \"score\": 78, \"contributors\": { \"hrv_balance\": 84, \"resting_heart_rate\": 71, \"sleep_balance\": 76 } },\n { \"day\": \"2026-05-28\", \"score\": 74, \"contributors\": { \"hrv_balance\": 79, \"resting_heart_rate\": 73, \"sleep_balance\": 72 } },\n { \"day\": \"2026-05-27\", \"score\": 69, \"contributors\": { \"hrv_balance\": 68, \"resting_heart_rate\": 80, \"sleep_balance\": 65 } }\n ]\n }\n },\n \"notes\": [\n \"All sample data is synthetic; tagged with is_demo=true.\",\n \"Real calls return live data from the Oura Cloud v2 API after OAuth setup.\"\n ]\n}\n```\n\nWhen you're ready to connect your own ring, call `oura_quickstart` for a\npersonalized 3-step setup walkthrough, then follow [Setup in 60 seconds](#setup-in-60-seconds).\n\n## Try it with your agent\n\nThree things to ask first:\n\n```text\nUse oura_connection_status to check setup, then run oura_daily_summary.\nGive me a 5-line operating brief for today.\n```\n\n```text\nCall oura_weekly_summary with response_format=json. Identify my biggest\nreadiness/sleep bottleneck and give me a next-week plan.\n```\n\n```text\nUse the oura_daily_checkin prompt, focus=sleep.\nDon't claim Oura can prove anything it can't.\n```\n\n## Data availability\n\nThis package uses the official Oura Cloud API v2. When this README says `raw`, it means the upstream Oura JSON for a supported endpoint — not raw device sensor streams.\n\n| Data | Available | Notes |\n|---|:---:|---|\n| Daily readiness score + contributors | ✓ | Requires `daily` scope |\n| Daily sleep score + sleep periods | ✓ | Requires `daily` and/or `sleep` scope |\n| Sleep stages + timing | ✓ | When Oura returns scored sleep |\n| Daily activity (steps, calories, MET) | ✓ | Requires `daily` scope |\n| Heart-rate time series | ✓ | When ring/membership/scope expose it |\n| HRV (overnight, via daily summaries) | ✓ | Surfaced through readiness contributors |\n| SpO2 (daily averages during sleep) | ✓ | Requires `spo2` scope; supported devices |\n| Workouts + sessions + tags | ✓ | Requires `workout`/`session`/`tag` scopes |\n| Personal info (DOB, sex, height, weight) | ✓ | Requires `personal` scope |\n| Continuous sensor telemetry | — | Not exposed by Oura Cloud API |\n\n## Tools\n\n**Start with these:**\n\n- `oura_demo` — realistic synthetic readiness/sleep/activity payloads (no account needed; see [Quickstart](#quickstart-see-the-data-before-you-connect))\n- `oura_quickstart` — personalized 3-step setup walkthrough that adapts to your current state\n- `oura_connection_status` — verify local setup before calling Oura\n- `oura_data_inventory` — inventory supported data domains, scopes, privacy modes and recommended first calls without calling Oura APIs.\n- `oura_daily_summary` — readiness, sleep, activity and SpO2 brief for today\n- `oura_weekly_summary` — scorecard, comparison vs prior week, next-week plan\n\n**Auth & diagnostics**\n\n- `oura_capabilities`, `oura_agent_manifest`, `oura_privacy_audit`, `oura_cache_status`\n- `oura_get_auth_url`, `oura_exchange_code`, `oura_revoke_access`\n\n**Profile**\n\n- `oura_get_personal_info`\n\n**Daily collections** (cursor-paginated with `next_token`, after/before filters and privacy-mode override)\n\n- `oura_list_daily_readiness`, `oura_list_daily_sleep`, `oura_list_daily_activity`, `oura_list_daily_spo2`\n- Offset ISO inputs keep their written calendar date when mapped to Oura's date-only `start_date` and `end_date` parameters; invalid dates fail before a network request.\n- Oura v2 has no integer page index. Resume with `next_token` from the previous response; if `truncated` is true, raise `limit` or set `all_pages`. See [docs/pagination.md](docs/pagination.md).\n\n**Detailed collections**\n\n- `oura_list_sleep`, `oura_list_workouts`, `oura_list_heartrate`, `oura_list_sessions`, `oura_list_tags`\n\n## Prompts\n\n- `oura_daily_checkin` — practical daily health and readiness check-in\n- `oura_weekly_review` — review trends across activity, sleep and heart context\n- `oura_heart_context_investigation` — investigate heart-rate records (privacy-aware)\n\n## Resources\n\n- `oura://capabilities`, `oura://agent-manifest`\n- `oura://personal-info`\n- `oura://latest/readiness` — the single newest readiness record. Use this for \"my latest readiness\": Oura serves collections oldest-first with no sort parameter, so `oura_list_daily_readiness` with `limit: 1` returns the **oldest** record in the window, not the newest.\n- `oura://summary/daily`, `oura://summary/weekly`\n\n## Privacy & security\n\n- OAuth tokens are stored in `~/.oura-mcp/tokens.json` with `0600` permissions and are never returned by tools.\n- The server never prints access or refresh tokens.\n- `OURA_PRIVACY_MODE` defaults to `structured`. Raw Oura JSON is opt-in via `raw` mode or per-call override.\n- Structured mode preserves upstream physiological fields, including fields added by Oura later, while removing GPS and secret-bearing values.\n- Personal info (DOB, sex, height, weight) is only accessible when the user grants the `personal` scope.\n- The MCP client never sees access or refresh tokens.\n- This is **not medical advice**. The server exposes user-authorized data for personal AI workflows, not diagnosis or treatment.\n\n## Configuration\n\n`setup` writes most of these into `~/.oura-mcp/config.json` (`0600`). Manual env override is supported:\n\n```bash\nOURA_CLIENT_ID=…\nOURA_CLIENT_SECRET=…\nOURA_REDIRECT_URI=http://127.0.0.1:3000/callback\n\n# Optional\nOURA_SCOPES=\"daily heartrate personal workout spo2\"\nOURA_PRIVACY_MODE=structured # summary | structured | raw\nOURA_CACHE=sqlite # optional read-through cache\nOURA_TOKEN_PATH=~/.oura-mcp/tokens.json\nOURA_CACHE_PATH=~/.oura-mcp/cache.sqlite\n```\n\n## Hermes / remote setup\n\n```bash\nnpx -y oura-mcp-unofficial setup --client hermes --no-auth\nnpx -y oura-mcp-unofficial auth # run locally if browser auth is needed\nnpx -y oura-mcp-unofficial doctor --client hermes\nhermes mcp test oura\n```\n\nAfter Hermes config changes, use `/reload-mcp` or `hermes mcp test oura`. Don't restart the gateway for normal data access.\n\nIf browser OAuth has to happen on a different machine than Hermes, run `auth` locally and copy `~/.oura-mcp/tokens.json` to the server with `chmod 600`.\n\n## Requirements\n\n- Node.js 20+\n- An Oura app at with redirect URI `http://127.0.0.1:3000/callback`\n\n## Development\n\n```bash\ngit clone https://github.com/davidmosiah/oura-mcp.git\ncd oura-mcp\nnpm install\nnpm test\nnpm run build\n```\n\nTest with MCP Inspector:\n\n```bash\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\n## Links\n\n- npm: \n- Docs site: \n- Legacy docs: \n- GitHub: \n- Delx Wellness registry: \n- Connector quality standard: \n- Oura Cloud API docs: \n\n\n\n## See also\n\nThe full [Delx Wellness](https://wellness.delx.ai) connector library:\n\n| Provider | Package | Repo |\n|---|---|---|\n| WHOOP | [`whoop-mcp-unofficial`](https://www.npmjs.com/package/whoop-mcp-unofficial) | [whoop-mcp](https://github.com/davidmosiah/whoop-mcp) |\n| Oura | [`oura-mcp-unofficial`](https://www.npmjs.com/package/oura-mcp-unofficial) | [oura-mcp](https://github.com/davidmosiah/oura-mcp) |\n| Garmin | [`garmin-mcp-unofficial`](https://www.npmjs.com/package/garmin-mcp-unofficial) | [garminmcp](https://github.com/davidmosiah/garminmcp) |\n| Strava | [`strava-mcp-unofficial`](https://www.npmjs.com/package/strava-mcp-unofficial) | [strava-mcp](https://github.com/davidmosiah/strava-mcp) |\n| Fitbit | [`fitbit-mcp-unofficial`](https://www.npmjs.com/package/fitbit-mcp-unofficial) | [fitbitmcp](https://github.com/davidmosiah/fitbitmcp) |\n| Withings | [`withings-mcp-unofficial`](https://www.npmjs.com/package/withings-mcp-unofficial) | [withingsmcp](https://github.com/davidmosiah/withingsmcp) |\n| Apple Health | [`apple-health-mcp-unofficial`](https://www.npmjs.com/package/apple-health-mcp-unofficial) | [apple-health-mcp](https://github.com/davidmosiah/apple-health-mcp) |\n| Polar | [`polar-mcp-unofficial`](https://www.npmjs.com/package/polar-mcp-unofficial) | [polarmcp](https://github.com/davidmosiah/polarmcp) |\n| Nourish (nutrition) | [`wellness-nourish`](https://www.npmjs.com/package/wellness-nourish) | [wellness-nourish](https://github.com/davidmosiah/wellness-nourish) |\n\n**One-command setup for Hermes** — preconfigures every connector above plus wellness skills + onboarding: [`delx-wellness-hermes`](https://github.com/davidmosiah/delx-wellness-hermes).\n\n\n\n## 📧 Contact & Support\n\n- 📨 **support@delx.ai** — general questions, integration help, partnerships\n- 🐛 **Bug reports / feature requests** — [GitHub Issues](https://github.com/davidmosiah/oura-mcp/issues)\n- 🐦 **Updates** — [@delx369](https://x.com/delx369) on X\n- 🌐 **Site** — [wellness.delx.ai](https://wellness.delx.ai)\n\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n## Disclaimer\n\nThis software is provided as-is. It is not a medical device, does not provide medical advice, and should not be used for diagnosis or treatment. Always consult qualified professionals for medical concerns.\n\n## Skill or MCP\n\nSame package, two doors. MCP registers tools on stdio/HTTP. The [skill](skill/SKILL.md) can drive the **same** tools through the CLI when the client has no MCP:\n\n```bash\nnpx -y oura-mcp-unofficial call oura_connection_status --json '{}'\n```\n\nCopy `skill/SKILL.md` into your agent skills dir.\n",
"bytes": 15944,
"sha": "3377dfb2cad871746bb163bf6c2b4774964477b509fdb33152c9b2900561d8e8",
"repo_slug": "davidmosiah/oura-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_davidmosiah_ouramcp_eb4f3e01/readme"
}
![\"Oura](\"assets/banner.png\")
\n![\"npm](\"https://img.shields.io/npm/v/oura-mcp-unofficial?style=for-the-badge&labelColor=0F172A&color=10B981&logo=npm&logoColor=white\")
![\"npm](\"https://img.shields.io/npm/dm/oura-mcp-unofficial?style=for-the-badge&labelColor=0F172A&color=0EA5A3&logo=npm&logoColor=white\")
![\"License](\"https://img.shields.io/badge/LICENSE-MIT-22C55E?style=for-the-badge&labelColor=0F172A\"){kind=icon}
![\"Site\"](\"https://img.shields.io/badge/SITE-wellness.delx.ai-0EA5A3?style=for-the-badge&labelColor=0F172A\"){kind=icon}
![\"GitHub](\"https://img.shields.io/github/stars/davidmosiah/oura-mcp?style=for-the-badge&labelColor=0F172A&color=FBBF24&logo=github\")
![\"Built](\"https://img.shields.io/badge/BUILT_FOR-MCP-7C3AED?style=for-the-badge&labelColor=0F172A\"){kind=icon}
![\"Hermes](\"https://img.shields.io/badge/HERMES-one--command_setup-10B981?style=for-the-badge&labelColor=0F172A\"){kind=icon}
![\"Oura\"](\"https://img.shields.io/badge/Oura-5C6068?style=for-the-badge&labelColor=0F172A&logoColor=white\"){kind=icon}