Oura Ring (read-only)

Oura Ring MCP Server (read-only)

Ask Claude, Cursor, VS Code or any MCP client about your Oura Ring readiness, sleep, HRV, activity, stress and heart rate, without giving it any way to change your data.

*"How did I sleep last night, and why is my readiness only 64?"*

*"Compare my HRV and lowest heart rate over the last 30 days."*

*"Show me last night's sleep stages and heart-rate curve."*

*"Does my readiness drop after days I tagged alcohol?"*

(Run the one-time auth step before or after installing.)

Why this server

• Read-only, enforced. Oura's API has no write endpoints for your data, and this client goes further: it can only send GET, refuses any URL outside /v2/usercollection/, never touches the webhook API, and every tool carries readOnlyHint: true. Tests fail the build otherwise.
• Answers whole questions in one call. get_daily_overview returns a day's readiness, sleep, naps, activity, stress, resilience, SpO2, workouts and tags together. get_trends returns a day table plus averages and readiness zones over up to 90 days.
• Model-friendly output. Compact JSON with hours, minutes, km and local times instead of seconds and meters; hypnograms as stage segments; heart rate aggregated into buckets. Pass raw: true for Oura's original objects.
• Degrades gracefully. If you untick a data type on Oura's consent page, combined tools list it under unavailable instead of failing.
• Your tokens stay on your machine. Your own Oura API application, OAuth with PKCE, a 0600 token file, and safe handling of Oura's single-use refresh tokens. No third-party servers, no telemetry.
• Try it without an account. OURA_SANDBOX=1 serves Oura's public sample data.

Quick start

You need Node.js 20.11+ and an Oura account. (Oura retired personal access tokens in December 2025, so OAuth is the only way in.)

1. Create an Oura API application (2 minutes)

1. Open cloud.ouraring.com/oauth/applications and create a new application.
2. Set the Redirect URI to http://localhost:8787/callback.
3. Copy the Client ID and Client Secret.

Applications work for up to 10 users without Oura's approval, which is plenty for personal use.

2. Connect your Oura account

npx -y @royreznik/oura-ring-mcp auth

Paste your Client ID and Client Secret when asked (the secret isn't echoed). Your browser opens Oura's consent page; leave every data type ticked and approve. Tokens are saved to ~/.config/oura-ring-mcp/tokens.json and refreshed automatically from then on.

(For scripts, set OURA_CLIENT_ID and OURA_CLIENT_SECRET instead of answering the prompts.)

3. Add it to your MCP client

Claude Code

As a plugin (adds the server plus an /oura:auth skill that walks you through connecting):

/plugin marketplace add royreznik/oura-ring-mcp

/plugin install oura@oura-ring-mcp

Or just the MCP server:

claude mcp add oura --scope user -- npx -y @royreznik/oura-ring-mcp

Claude Desktop, Cursor, Windsurf

Add to the client's MCP config (Claude Desktop: Settings → Developer → Edit Config; Cursor: ~/.cursor/mcp.json; Windsurf: ~/.codeium/windsurf/mcp_config.json):

{

"mcpServers": { "oura": { "command": "npx", "args": ["-y", "@royreznik/oura-ring-mcp"] } } }

For Claude Desktop you can also install the .mcpb bundle from the latest release.

VS Code (GitHub Copilot)

.vscode/mcp.json (or your user mcp.json):

{

"servers": { "oura": { "type": "stdio", "command": "npx", "args": ["-y", "@royreznik/oura-ring-mcp"] } } }

</details>

OpenAI Codex CLI

~/.codex/config.toml:

[mcp_servers.oura]

command = "npx" args = ["-y", "@royreznik/oura-ring-mcp"]

</details>

Docker

Run auth on the host first, then mount the token directory:

docker build -t oura-ring-mcp https://github.com/royreznik/oura-ring-mcp.git

docker run -i --rm -v ~/.config/oura-ring-mcp:/home/node/.config/oura-ring-mcp oura-ring-mcp

</details>

Then ask: *"Give me my Oura overview for today."*

Try it without an account

claude mcp add oura-sandbox --env OURA_SANDBOX=1 -- npx -y @royreznik/oura-ring-mcp

Sandbox mode serves Oura's public sample data. No auth step, no personal data.

Tools

List tools accept start / end (YYYY-MM-DD, inclusive), a days shortcut and next_token. See the [tool reference](docs/tools.md) for details.

Configuration

oura-ring-mcp            Start the MCP server on stdio (what your MCP client runs)

oura-ring-mcp auth Connect your Oura account (opens your browser) oura-ring-mcp status Check the stored connection oura-ring-mcp logout Delete the locally stored tokens oura-ring-mcp --version

"Today" is computed in your computer's timezone, which should match the timezone your Oura app uses.

Privacy and security

• oura-ring-mcp talks only to api.ouraring.com (plus your browser visiting cloud.ouraring.com during auth). No telemetry, no intermediary server.
• Tokens and your client secret live in one file only your user can read (0600). They are never logged or returned by tools.
• Your MCP client sends tool results to its language model. Health data you ask about is shared with that model provider under its terms.
• To disconnect, run oura-ring-mcp logout. To revoke access completely, delete the application at cloud.ouraring.com/oauth/applications or revoke it in your Oura account.

Details: PRIVACY.md, SECURITY.md.

How authentication works

• OAuth 2 authorization-code flow with PKCE (S256) and a random state, captured by a loopback-only callback server.
• Oura refresh tokens are single-use. oura-ring-mcp refreshes shortly before expiry (and on a 401), one refresh at a time, under a lock file so several clients on one machine (e.g. Claude Desktop and Claude Code) never refresh at once, and writes new tokens atomically. If a write fails, the new tokens stay in memory so a full disk can't log you out.
• Rate limits (429, honouring Retry-After), server errors, timeouts (30s) and network errors are retried with backoff. Cancelling a request in your client stops its Oura calls.

Troubleshooting

npx -y @royreznik/oura-ring-mcp status

Development

npm install

npm test # unit, MCP integration, end-to-end and packaging tests (no network) npm run smoke:sandbox # every tool against Oura's live sandbox API npm run smoke:live # every tool against your account (after auth); prints only counts npm run inspect # MCP Inspector

See CONTRIBUTING.md. The one hard rule: oura-ring-mcp stays read-only.

Credits and legal

Architecture, auth and test approach are adapted from whoop-mcp by Oryan Omer (MIT).

MIT © Roy Reznik. Unofficial project, not affiliated with or endorsed by Oura Heal