Oura Mcp Unofficial

by davidmosiah

278 downloads

Not rated

GitHub Website

About

Local-first MCP server for Oura Ring readiness, sleep, HRV — Claude/Cursor/ChatGPT ready

Details

Author: davidmosiah
Downloads: 278
Categories: AI

- Local-first: OAuth tokens never leave your machine
- Supports readiness, sleep, activity, HRV, SpO2, workouts, sessions, tags, personal info
- Privacy‑mode defaults to structured; raw JSON is opt‑in
- Demo mode (oura_demo) works without an Oura account
- Includes prompts like oura_daily_checkin and oura_weekly_review
- Caching opt‑in via SQLite; configurable via env or ~/.oura-mcp/config.json
- Compatible with Hermes‑based remote setups

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Oura Mcp Unofficial

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

From the repository

First create an Oura app at cloud.ouraring.com with redirect URI http://127.0.0.1:3000/callback. Then run npx -y oura-mcp-unofficial setup (paste client id + secret), npx -y oura-mcp-unofficial auth (opens browser for OAuth), and npx -y oura-mcp-unofficial doctor to verify. Add the server to your MCP client config as a npx command, or for Claude Desktop run setup --client claude to auto-write the snippet. You can also call oura_demo before connecting to see synthetic payloads.

`oura_data_inventory`

Inventory supported Oura data domains, auth scope requirements, privacy boundary and recommended first calls. Does not call Oura APIs or expose user data.

`oura_agent_manifest`

Machine-readable install, runtime and client guidance for AI agents. Does not call Oura or expose secrets.

`oura_capabilities`

Explain supported Oura data, privacy boundaries, recommended agent workflow and project links.

`oura_quickstart`

Personalized 3-step setup walkthrough for the human user. Adapts to current state (env vars set? token present? what's next?). Call this first when the user asks 'how do I connect Oura?'

`oura_demo`

Returns realistic example payloads of oura_daily_summary, oura_wellness_context, and oura_list_daily_readiness so agents see the contract before calling real Oura APIs.

`oura_profile_get`

Read the shared Delx wellness profile (~/.delx-wellness/profile.json). Returns the user's preferred name, body basics, goals, devices, training context, nutrition context, agent preferences, and missing critical fields. Cross-connector — the same profile is also available from other Delx Wellness MCPs (WHOOP, Garmin, Nourish, Fitbit, etc). Read-only.

`oura_profile_update`

Persist a partial patch to the shared Delx wellness profile (~/.delx-wellness/profile.json). REQUIRES explicit_user_intent=true. Top-level fields stored: profile (preferred_name, language, timezone, units, age_or_birth_year, height, weight, sex_or_gender_context), goals, devices, training, nutrition, preferences, safety, notes. NEVER stores OAuth tokens, API keys, refresh tokens, cookies, or any secret-shaped field — writes will be rejected at validation time. Cross-connector — the same profile is read by other Delx Wellness MCPs.

`oura_onboarding`

Return the 11-question Delx wellness onboarding flow (in English or pt-BR) plus the current shared profile state and missing critical fields. Read-only. The agent should ask these questions one-by-one, then call oura_profile_update with explicit_user_intent=true to save. The same profile is reused by every Delx Wellness connector (WHOOP, Garmin, Nourish, etc.) — agents can call the equivalent {connector}_onboarding tools to cover their respective domains, or rely on this one since all connectors share the same questions.

`oura_get_auth_url`

Generate an Oura OAuth authorization URL. Use this first when no local token exists.

`oura_exchange_code`

Exchange an Oura OAuth authorization code for local tokens. Tokens are stored locally with 0600 permissions and are never returned. Requires explicit user action: the user must complete browser OAuth and supply the authorization code (agents must not invent codes).

`oura_get_personal_info`

Get Oura personal profile fields available to the authorized app. Requires the personal scope.

`oura_list_daily_activity`

List daily Oura activity summaries. Supports start/end date filters through after/before and Oura cursor pagination.

`oura_list_daily_sleep`

List daily Oura sleep score summaries. Requires daily or sleep data access granted by the user. Not medical advice.

`oura_list_daily_readiness`

List Oura readiness summaries and contributors. Requires daily scope. Not medical advice.

`oura_list_sleep`

List detailed Oura sleep period records, including sleep stages and timing where available. Requires the daily scope (Oura has no separate sleep OAuth scope). Not medical advice.

`oura_list_workouts`

List Oura workout summaries. Requires workout scope.

`oura_list_heartrate`

List Oura heart-rate time-series records where the user's ring and membership expose them. Requires heartrate scope. Not medical advice.

`oura_list_daily_spo2`

List daily Oura SpO2 averages recorded during sleep when available. Requires spo2 scope. Not medical advice.

`oura_list_sessions`

List guided and unguided Oura app sessions when the user granted session scope.

`oura_list_tags`

List user-entered Oura tags when the user granted tag scope.

`oura_connection_status`

Check local Oura config, token file, Node version, privacy mode, cache readiness and optional MCP client readiness without calling Oura or exposing secrets.

`oura_cache_status`

Show optional local SQLite cache status. Enable with OURA_CACHE=sqlite or OURA_CACHE=true.

`oura_privacy_audit`

Return local privacy, cache, token-path and env-presence posture without revealing secret values.

`oura_revoke_access`

Revoke the current Oura OAuth grant and delete the local token file. Use only when the user explicitly wants to disconnect Oura. Gated by explicit_user_intent: true (requires explicit user intent).

`oura_daily_summary`

Build a practical daily summary from Oura readiness, sleep, activity, heart-rate and SpO2 data when available. Read-only and non-medical.

`oura_weekly_summary`

Build a weekly Oura scorecard with readiness, sleep, activity, HRV availability, bottlenecks and actions. Read-only and non-medical.

`oura_wellness_context`

Normalize Oura readiness, sleep and activity load into the shared wellness_context shape for recommendation engines.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "oura mcp unofficial": {
            "oura": {
                "command": "npx",
                "args": [
                    "-y",
                    "oura-mcp-unofficial"
                ]
            }
        }
    }
}

McpServers

{
    "oura": {
        "command": "npx",
        "args": [
            "-y",
            "oura-mcp-unofficial"
        ]
    }
}

<h1 align="center">Oura MCP</h1>

<h3 align="center">
Give your AI agent your Oura readiness, sleep, activity and HRV — without copy-pasting from the Oura app.<br>
Local-first MCP server — <strong>tokens never leave your machine</strong>.
</h3>

> ⚡ One-command install with Delx Wellness for Hermes:
> npx -y delx-wellness-hermes setup — preconfigures this connector and the other 8 in a dedicated Hermes profile.
>
> Or wire it standalone into Claude Desktop / Cursor / ChatGPT Desktop — see the install section below.

---

Local-first MCP server that connects AI agents to your Oura Ring readiness, sleep, activity and HRV data.

> 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.

Built by David Mosiah 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.

Part of Delx Wellness, a registry of local-first wellness MCP connectors.

> 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.

Why this exists

Oura 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).

This 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.

Setup in 60 seconds

You'll need an Oura app (create one here) with redirect URI http://127.0.0.1:3000/callback.

npx -y oura-mcp-unofficial setup    # interactive: paste client id + secret
npx -y oura-mcp-unofficial auth     # opens browser, captures the OAuth code
npx -y oura-mcp-unofficial doctor   # verifies you're ready

Recommended scopes:

daily heartrate personal sleep workout spo2

Then add this to your MCP client config:

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "oura-mcp-unofficial"]
    }
  }
}

For Claude Desktop, run setup --client claude and the snippet is written for you.

Quickstart: see the data before you connect

No Oura account yet? Call oura_demo to get realistic example payloads for the
readiness, sleep and daily-summary tools, so your agent learns the data contract
before any OAuth setup. All values are synthetic and tagged is_demo: true.

Call oura_demo and show me what the readiness and sleep data looks like.

Real output from oura_demo (response_format=json, dates are relative to today):

{
  "ok": true,
  "is_demo": true,
  "sample": {
    "oura_daily_summary": {
      "date": "2026-05-29",
      "readiness": { "score": 78, "temperature_deviation": -0.1, "hrv_balance": 84 },
      "sleep": { "score": 82, "efficiency": 89, "duration_min": 451, "deep_min": 92, "rem_min": 108 },
      "activity": { "score": 86, "steps": 9420, "active_calories": 412, "target_calories": 500 },
      "spo2": { "average": 96.8 }
    },
    "oura_wellness_context": {
      "window": "last_24h",
      "readiness_score": 78,
      "readiness_band": "good",
      "sleep_score": 82,
      "sleep_efficiency": 89,
      "hrv_balance": 84,
      "recommendation": "Solid readiness and efficient sleep — green light for moderate-to-high intensity. A protein-forward breakfast keeps HRV trending up."
    },
    "oura_list_daily_readiness": {
      "count": 3,
      "records": [
        { "day": "2026-05-29", "score": 78, "contributors": { "hrv_balance": 84, "resting_heart_rate": 71, "sleep_balance": 76 } },
        { "day": "2026-05-28", "score": 74, "contributors": { "hrv_balance": 79, "resting_heart_rate": 73, "sleep_balance": 72 } },
        { "day": "2026-05-27", "score": 69, "contributors": { "hrv_balance": 68, "resting_heart_rate": 80, "sleep_balance": 65 } }
      ]
    }
  },
  "notes": [
    "All sample data is synthetic; tagged with is_demo=true.",
    "Real calls return live data from the Oura Cloud v2 API after OAuth setup."
  ]
}

When you're ready to connect your own ring, call oura_quickstart for a
personalized 3-step setup walkthrough, then follow Setup in 60 seconds.

Try it with your agent

Three things to ask first:

Use oura_connection_status to check setup, then run oura_daily_summary.
Give me a 5-line operating brief for today.

Call oura_weekly_summary with response_format=json. Identify my biggest
readiness/sleep bottleneck and give me a next-week plan.

Use the oura_daily_checkin prompt, focus=sleep.
Don't claim Oura can prove anything it can't.

Data availability

This 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.

| Data | Available | Notes |
|---|:---:|---|
| Daily readiness score + contributors | ✓ | Requires daily scope |
| Daily sleep score + sleep periods | ✓ | Requires daily and/or sleep scope |
| Sleep stages + timing | ✓ | When Oura returns scored sleep |
| Daily activity (steps, calories, MET) | ✓ | Requires daily scope |
| Heart-rate time series | ✓ | When ring/membership/scope expose it |
| HRV (overnight, via daily summaries) | ✓ | Surfaced through readiness contributors |
| SpO2 (daily averages during sleep) | ✓ | Requires spo2 scope; supported devices |
| Workouts + sessions + tags | ✓ | Requires workout/session/tag scopes |
| Personal info (DOB, sex, height, weight) | ✓ | Requires personal scope |
| Continuous sensor telemetry | — | Not exposed by Oura Cloud API |

Tools

Start with these:

- oura_demo — realistic synthetic readiness/sleep/activity payloads (no account needed; see Quickstart)
- oura_quickstart — personalized 3-step setup walkthrough that adapts to your current state
- oura_connection_status — verify local setup before calling Oura
- oura_data_inventory — inventory supported data domains, scopes, privacy modes and recommended first calls without calling Oura APIs.
- oura_daily_summary — readiness, sleep, activity and SpO2 brief for today
- oura_weekly_summary — scorecard, comparison vs prior week, next-week plan

Auth & diagnostics

- oura_capabilities, oura_agent_manifest, oura_privacy_audit, oura_cache_status
- oura_get_auth_url, oura_exchange_code, oura_revoke_access

Profile

- oura_get_personal_info

Daily collections (paginated, with after/before filters and privacy-mode override)

- oura_list_daily_readiness, oura_list_daily_sleep, oura_list_daily_activity, oura_list_daily_spo2

Detailed collections

- oura_list_sleep, oura_list_workouts, oura_list_heartrate, oura_list_sessions, oura_list_tags

Prompts

- oura_daily_checkin — practical daily health and readiness check-in
- oura_weekly_review — review trends across activity, sleep and heart context
- oura_heart_context_investigation — investigate heart-rate records (privacy-aware)

Resources

- oura://capabilities, oura://agent-manifest
- oura://personal-info
- oura://latest/readiness
- oura://summary/daily, oura://summary/weekly

Privacy & security

- OAuth tokens are stored in ~/.oura-mcp/tokens.json with 0600 permissions and are never returned by tools.
- The server never prints access or refresh tokens.
- OURA_PRIVACY_MODE defaults to structured. Raw Oura JSON is opt-in via raw mode or per-call override.
- Personal info (DOB, sex, height, weight) is only accessible when the user grants the personal scope.
- The MCP client never sees access or refresh tokens.
- This is not medical advice. The server exposes user-authorized data for personal AI workflows, not diagnosis or treatment.

Configuration

setup writes most of these into ~/.oura-mcp/config.json (0600). Manual env override is supported:

OURA_CLIENT_ID=…
OURA_CLIENT_SECRET=…
OURA_REDIRECT_URI=http://127.0.0.1:3000/callback
Optional
OURA_SCOPES="daily heartrate personal sleep workout spo2"
OURA_PRIVACY_MODE=structured        # summary | structured | raw
OURA_CACHE=sqlite                   # optional read-through cache
OURA_TOKEN_PATH=~/.oura-mcp/tokens.json
OURA_CACHE_PATH=~/.oura-mcp/cache.sqlite

Hermes / remote setup

npx -y oura-mcp-unofficial setup --client hermes --no-auth
npx -y oura-mcp-unofficial auth                      # run locally if browser auth is needed
npx -y oura-mcp-unofficial doctor --client hermes
hermes mcp test oura

After Hermes config changes, use /reload-mcp or hermes mcp test oura. Don't restart the gateway for normal data access.

If 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.

Requirements

- Node.js 20+
- An Oura app at <https://cloud.ouraring.com/oauth/applications> with redirect URI http://127.0.0.1:3000/callback

Development

git clone https://github.com/davidmosiah/oura-mcp.git
cd oura-mcp
npm install
npm test
npm run build

Test with MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Links

- npm: <https://www.npmjs.com/package/oura-mcp-unofficial>
- Docs site: <https://wellness.delx.ai/connectors/oura>
- Legacy docs: <https://ouramcp.vercel.app/>
- GitHub: <https://github.com/davidmosiah/oura-mcp>
- Delx Wellness registry: <https://github.com/davidmosiah/delx-wellness>
- Connector quality standard: <https://github.com/davidmosiah/delx-wellness/blob/main/docs/connector-quality-standard.md>
- Oura Cloud API docs: <https://cloud.ouraring.com/docs/authentication>

📧 Contact & Support

- 📨 support@delx.ai — general questions, integration help, partnerships
- 🐛 Bug reports / feature requests — GitHub Issues
- 🐦 Updates — @delx369 on X
- 🌐 Site — wellness.delx.ai

License

MIT — see LICENSE.

Disclaimer

This 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.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

oura_data_inventory

oura_agent_manifest

oura_capabilities

oura_quickstart

oura_demo

oura_profile_get

oura_profile_update

oura_onboarding

oura_get_auth_url

oura_exchange_code

oura_get_personal_info

oura_list_daily_activity

oura_list_daily_sleep

oura_list_daily_readiness

oura_list_sleep

oura_list_workouts

oura_list_heartrate

oura_list_daily_spo2

oura_list_sessions

oura_list_tags

oura_connection_status

oura_cache_status

oura_privacy_audit

oura_revoke_access

oura_daily_summary

oura_weekly_summary

oura_wellness_context

Claude Desktop / Cursor

McpServers

Why this exists

Setup in 60 seconds

Quickstart: see the data before you connect

Try it with your agent

Data availability

Tools

Prompts

Resources

Privacy & security

Configuration

Optional

Hermes / remote setup

Requirements

Development

Links

See also

📧 Contact & Support

License

Disclaimer

Install

More like this

Context 7

1Panel

🔎 GPT Researcher

Serena

FastMCP v2 🚀

MaxKB

`oura_data_inventory`

`oura_agent_manifest`

`oura_capabilities`

`oura_quickstart`

`oura_demo`

`oura_profile_get`

`oura_profile_update`

`oura_onboarding`

`oura_get_auth_url`

`oura_exchange_code`

`oura_get_personal_info`

`oura_list_daily_activity`

`oura_list_daily_sleep`

`oura_list_daily_readiness`

`oura_list_sleep`

`oura_list_workouts`

`oura_list_heartrate`

`oura_list_daily_spo2`

`oura_list_sessions`

`oura_list_tags`

`oura_connection_status`

`oura_cache_status`

`oura_privacy_audit`

`oura_revoke_access`

`oura_daily_summary`

`oura_weekly_summary`

`oura_wellness_context`