Skip to main content
Glama
oura-ring-mcp-server

oura-ring-mcp-server

oura-ring-mcp-server

Node.js CI npm version License: MIT

A Model Context Protocol server for the Oura Ring API v2. Point Claude (or any MCP client) at your Oura data and ask about your sleep, readiness, activity, heart rate, workouts, and more.

Built with somamcp (telemetry + introspection), functype (typed error handling), and zod.

Design

Rather than one tool per endpoint, the server exposes a single consolidated oura_data tool with a collection parameter. This keeps the tool schema small (low token cost) while covering every Oura usercollection endpoint. The tool validates that the parameters you pass are legal for the chosen collection and returns actionable messages when they are not.

Related MCP server: oura-mcp-server

Requirements

  • Node.js 24+ (pinned in .nvmrc)

  • An Oura OAuth2 application — register one at cloud.ouraring.com/oauth/applications to get a client ID and secret. Set the redirect URI to http://localhost:8080/callback and enable the read scopes you want. The default requests the full set — email personal daily heartrate tag workout session spo2 ring_configuration stress heart_health — so every collection works (heart_health in particular gates vO2_max and daily_cardiovascular_age).

    Oura stopped issuing new personal access tokens in December 2025, so OAuth2 is the path for new setups. A previously-issued PAT still works — see Authentication.

Authentication

The server authenticates to Oura with an OAuth2 access token that it refreshes automatically. You authorize once with the built-in login command:

# with OURA_CLIENT_ID and OURA_CLIENT_SECRET set in the environment
npx -y oura-ring-mcp-server login

This opens your browser for consent, captures the redirect on http://localhost:8080/callback, and writes the tokens to ~/.config/oura-ring-mcp/tokens.json (override with OURA_TOKEN_STORE). Oura refresh tokens are single-use, so the server owns and rotates them in that store from then on — you never put a refresh token in your environment. The MCP server reads the store on startup; re-run login only if the refresh token is ever revoked.

Legacy PAT: if you still have a valid personal access token, set OURA_API_KEY instead and skip the OAuth setup. When both are configured, OAuth takes precedence.

Usage

Claude Desktop / Claude Code

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "oura-ring-mcp-server"],
      "env": {
        "OURA_CLIENT_ID": "your-oauth-client-id",
        "OURA_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

That runs the server over stdio, which is what most MCP clients expect. Run login once first (see Authentication) so the token store exists.

Configuration

Env var

Required

Default

Description

OURA_CLIENT_ID

for OAuth

—

Oura OAuth2 client ID.

OURA_CLIENT_SECRET

for OAuth

—

Oura OAuth2 client secret.

OURA_API_KEY

for legacy PAT

—

Legacy personal access token (Bearer). Alternative to the OAuth pair.

OURA_REDIRECT_URI

no

http://localhost:8080/callback

Redirect URI for login; must match the Oura app registration.

OURA_SCOPES

no

full read set (see Requirements)

Space-separated scopes requested during login.

OURA_TOKEN_STORE

no

~/.config/oura-ring-mcp/tokens.json

Path to the OAuth token store.

OURA_SANDBOX

no

false

Use Oura's /sandbox/ demo data instead of your real data.

TRANSPORT_TYPE

no

stdio

stdio or httpStream.

PORT

no

3000

Port for httpStream transport.

HOST

no

0.0.0.0

Host for httpStream transport.

OURA_TELEMETRY_FILE

no

—

Write NDJSON telemetry events to this file path (safe under any transport).

OURA_TELEMETRY_CONSOLE

no

true

Console telemetry, httpStream only (never enabled under stdio).

HTTP transport

For a long-running / networked deployment:

OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... TRANSPORT_TYPE=httpStream PORT=3000 npx -y oura-ring-mcp-server

The MCP endpoint is served at /mcp; somamcp also exposes a public GET /health probe.

The oura_data tool

Parameter

Applies to

Notes

collection

all

Which data collection to fetch (see below).

start_date / end_date

daily collections

YYYY-MM-DD. Omitted → last 7 days.

start_datetime / end_datetime

heartrate, ring_battery_level

ISO-8601. Omitted → last 24 hours.

latest

heartrate, ring_battery_level

Return only the most recent sample.

document_id

collections with a detail route

Fetch a single record by id.

next_token

list collections

Pagination cursor from a previous response.

fields

list collections

Comma-separated sparse fieldset.

Collections

Daily (start_date/end_date): daily_activity, daily_sleep, daily_readiness, daily_spo2, daily_stress, daily_resilience, daily_cardiovascular_age, vO2_max, sleep, sleep_time, session, workout, tag, enhanced_tag, rest_mode_period

Time-series (start_datetime/end_datetime): heartrate, ring_battery_level

List / singleton: ring_configuration, personal_info

Example prompts

  • "What was my average readiness score last week?"

  • "Show my sleep stages for the night of 2026-06-20."

  • "Get my most recent heart rate reading."

  • "How many workouts did I log this month and how long were they?"

Development

pnpm install
pnpm validate   # format + lint + typecheck + test + build
pnpm dev        # watch build
pnpm inspect    # run against the MCP Inspector

Try it without a ring by setting OURA_SANDBOX=true to hit Oura's demo dataset.

License

MIT

Available Tools

2 tools
infoA
Read-only

Returns identity and build information for this server (name, version, build commit, runtime, capability counts)

Inputs: no named parameters.

oura_dataA
Read-only

Fetch data from the Oura Ring API v2.

Pick a collection and provide the matching date range:

  • Daily collections use start_date/end_date (YYYY-MM-DD). If both are omitted, the last 7 days are returned.

  • Time-series collections (heartrate, ring_battery_level) use start_datetime/end_datetime (ISO-8601), or latest: true.

  • personal_info takes no parameters; ring_configuration is a plain list.

  • Any list collection with a document id can be fetched directly via document_id. Large lists paginate: pass the returned next_token to fetch the next page.

Available collections:

  • daily_activity: Daily activity summary: steps, calories, activity score.

  • daily_sleep: Daily sleep summary and sleep score.

  • daily_readiness: Daily readiness summary and readiness score.

  • daily_spo2: Daily average blood oxygen (SpO2) percentage.

  • daily_stress: Daily stress and recovery high/normal durations.

  • daily_resilience: Daily resilience level derived from recovery metrics.

  • daily_cardiovascular_age: Daily cardiovascular age estimate.

  • vO2_max: VO2 max (cardiorespiratory fitness) estimates.

  • sleep: Detailed per-period sleep sessions (stages, HRV, heart rate).

  • sleep_time: Recommended/ideal bedtime windows.

  • session: Guided/unguided moment sessions (meditation, breathing, rest).

  • workout: Recorded workouts with intensity, calories, and duration.

  • tag: Legacy user-entered tags.

  • enhanced_tag: Enhanced user-entered tags (current tag model).

  • rest_mode_period: Rest mode periods (recovery/illness) the user enabled.

  • heartrate: Time-series heart rate samples.

  • ring_battery_level: Time-series ring battery level samples.

  • ring_configuration: Ring hardware configuration records (size, color, firmware, design).

  • personal_info: The user's personal info: age, weight, height, biological sex, email.

Inputs: collection (required), fields, latest, end_date, +5 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have clearly distinct purposes: 'info' returns server metadata, while 'oura_data' fetches Oura Ring API data. There is no overlap or ambiguity.

    Naming Consistency3/5

    With only two tools, a consistent naming pattern is hard to establish. 'info' is a noun, while 'oura_data' uses underscore separation. The names are not chaotic but lack a strong, predictable pattern.

    Tool Count3/5

    Having only two tools for a server that covers a wide range of health data (18+ collections) feels thin. The generic 'oura_data' tool consolidates all data retrieval, which is efficient but potentially overloaded.

    Completeness3/5

    The server covers read access to many Oura Ring data collections, but lacks any write operations (create, update, delete). For a comprehensive API surface, this is a notable gap.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers