Skip to main content
Glama
jordanburke

oura-ring-mcp-server

by jordanburke
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
TypeScript
Hybrid

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)

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true. Description adds specific content details (name, version, etc.) but doesn't disclose additional behavioral traits beyond what annotations provide.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single, front-loaded sentence with no extraneous words. Every part earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and annotations, the description adequately covers the tool's output by listing the categories. Missing output schema is a minor gap but acceptable.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters defined; schema coverage is 100%. The description doesn't need to add parameter info, so baseline score applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description specifies a clear verb ('returns') and resource ('identity and build information'), listing exact fields. Distinguishes from sibling 'oura_data' which likely deals with data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit when-to-use instructions, but the purpose is clear and different from the only sibling. Context signals imply no alternatives needed.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
fieldsNoComma-separated sparse fieldset to limit returned fields (list endpoints only).
latestNoReturn only the most recent sample (heartrate / ring_battery_level only).
end_dateNoEnd date (inclusive) for daily collections.
collectionYesWhich Oura data collection to fetch. Determines which date parameters apply.
next_tokenNoPagination cursor returned as `next_token` by a previous list response.
start_dateNoStart date (inclusive) for daily collections.
document_idNoFetch a single document by id instead of a list. Not supported by all collections.
end_datetimeNoEnd datetime for time-series collections.
start_datetimeNoStart datetime for time-series collections (heartrate, ring_battery_level).

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, which the description confirms by implying data retrieval. The description adds valuable behavioral context: daily collections have a 7-day default, time-series require ISO-8601 datetimes, list collections paginate via next_token, and document_id fetches a single record. No annotation contradiction exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is fairly long but well-structured with a clear opening, bullet-point collection list, and separate parameter usage notes. While every sentence adds value, it could be slightly more concise by grouping common parameter patterns. Still, it remains readable and informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (9 parameters, 19 collections, no output schema), the description covers all necessary usage contexts: parameter selection by collection type, default behaviors, pagination, and single-document retrieval. It is complete enough for an agent to use the tool correctly without needing additional external documentation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, providing a baseline of 3. The description adds meaning by explaining which parameters apply to which collection types, the default date range, and the semantics of latest and document_id. This goes beyond the schema's field descriptions, justifying a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with 'Fetch data from the Oura Ring API v2' and enumerates all 19 collection types with brief summaries, clearly distinguishing the resource and scope. It separates daily, time-series, and singleton collections, making the tool's purpose unambiguous and differentiating it from a sibling like 'info'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on which date parameters to use for daily vs. time-series collections, explains the default behavior when omitted, and covers pagination via next_token. However, it does not explicitly state when to prefer this tool over the sibling 'info' tool, which serves a distinct purpose, so a full 5 is not warranted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.2.0
    • First observedinfo
    • First observedoura_data
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0
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

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/jordanburke/oura-ring-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server