oura-ring-mcp-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@oura-ring-mcp-server how did I sleep last night?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
oura-ring-mcp-server
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/callbackand 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_healthin particular gatesvO2_maxanddaily_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 loginThis 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 |
| for OAuth | — | Oura OAuth2 client ID. |
| for OAuth | — | Oura OAuth2 client secret. |
| for legacy PAT | — | Legacy personal access token (Bearer). Alternative to the OAuth pair. |
| no |
| Redirect URI for |
| no | full read set (see Requirements) | Space-separated scopes requested during |
| no |
| Path to the OAuth token store. |
| no |
| Use Oura's |
| no |
|
|
| no |
| Port for |
| no |
| Host for |
| no | — | Write NDJSON telemetry events to this file path (safe under any transport). |
| no |
| Console telemetry, |
HTTP transport
For a long-running / networked deployment:
OURA_CLIENT_ID=... OURA_CLIENT_SECRET=... TRANSPORT_TYPE=httpStream PORT=3000 npx -y oura-ring-mcp-serverThe MCP endpoint is served at /mcp; somamcp also exposes a public GET /health probe.
The oura_data tool
Parameter | Applies to | Notes |
| all | Which data collection to fetch (see below). |
| daily collections |
|
|
| ISO-8601. Omitted → last 24 hours. |
|
| Return only the most recent sample. |
| collections with a detail route | Fetch a single record by id. |
| list collections | Pagination cursor from a previous response. |
| 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 InspectorTry it without a ring by setting OURA_SANDBOX=true to hit Oura's demo dataset.
License
MIT
Available Tools
2 toolsinfoARead-only
Returns identity and build information for this server (name, version, build commit, runtime, capability counts)
Inputs: no named parameters.
oura_dataARead-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), orlatest: true.personal_infotakes no parameters;ring_configurationis a plain list.Any list collection with a document id can be fetched directly via
document_id. Large lists paginate: pass the returnednext_tokento 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
Scored across 2 tools
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.
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.
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.
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
Related MCP Connectors
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
Hosted Apple Health MCP for Claude and ChatGPT, works outside the US. iPhone app, no local server.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for the Oura Ring API v2, providing access to sleep, activity, readiness, heart rate, and workout data via OAuth.5145 npm1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to query Oura Ring health data (sleep, readiness, activity, heart rate, SpO2, stress) via a remote MCP server.7 npmMIT
- AlicenseAqualityDmaintenanceComprehensive MCP server for the Oura Ring API v2, exposing 17 tools to access sleep, activity, heart rate, stress, SpO2, workouts, and user data.171MIT
- AlicenseNot gradedqualityBmaintenanceA Model Context Protocol (MCP) server that provides AI assistants with structured, semantic access to your Oura Ring health data.1MIT