🏥

gjlumsden.OuraMcp

An independently developed MCP server exposing Oura Ring health data (sleep, activity, readiness, stress, heart rate, SpO2, and more) for AI assistants like GitHub Copilot and Claude. Not affiliated with, endorsed by, or sponsored by Ōura Health Oy.

0 installs

Trust: 34 — Low

Healthcare

Ask AI about gjlumsden.OuraMcp

I know everything about gjlumsden.OuraMcp. Ask me about installation, configuration, usage, or troubleshooting.

0/500

Loading tools...

Reviews

Documentation

Oura Ring MCP Server

A .NET 10 MCP server that exposes Oura Ring health and wellness data as Model Context Protocol tools for AI assistants.

Disclaimer: This is an independently developed open source project. It is not affiliated with, endorsed by, or sponsored by Ōura Health Oy. "Oura" and "Oura Ring" are trademarks of Ōura Health Oy. This project uses the Oura API v2 but is not maintained or supported by Oura. For official Oura support, visit ouraring.com.

Overview

This server connects to the Oura API v2 and surfaces ring data — sleep, activity, readiness, heart rate, and more — as MCP tools over STDIO transport. Authentication is automatic on first launch: the server opens your browser for Oura authorization the first time it starts, and tokens are persisted locally for silent reuse and refresh. An explicit oura-mcp login command is also available for headless or ahead-of-time setup.

Getting Started

Prerequisites

.NET 10 SDK
An Oura API application registered at https://developer.ouraring.com/ (redirect URI: http://localhost:8742/callback/)

1. Install

dotnet tool install -g gjlumsden.OuraMcp

No-Install Option

Or run without installing (requires .NET 10):

dnx -y gjlumsden.OuraMcp

2. Configure Your MCP Client

Add the server to your MCP client config. The client launches the server process via STDIO and injects your Oura credentials as environment variables. The first time the server starts, it will automatically open your browser to authorize with Oura — no separate login step is required. Tokens are then saved to ~/.oura-mcp/tokens.json and reused/refreshed on subsequent launches.

VS Code (GitHub Copilot) — add to .vscode/mcp.json or user settings:

{
  "mcpServers": {
    "oura": {
      "command": "oura-mcp",
      "env": {
        "OURA_CLIENT_ID": "<your-client-id>",
        "OURA_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "oura": {
      "command": "oura-mcp",
      "env": {
        "OURA_CLIENT_ID": "<your-client-id>",
        "OURA_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

Using the no-install (dnx) option?

Replace the server entry with:

{
  "mcpServers": {
    "oura": {
      "command": "dnx",
      "args": ["-y", "gjlumsden.OuraMcp"],
      "env": {
        "OURA_CLIENT_ID": "<your-client-id>",
        "OURA_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

Prefer to log in ahead of time (headless / CI)?

You can authenticate explicitly before wiring the server into an MCP client by running the login subcommand:

$env:OURA_CLIENT_ID = "<your-client-id>"
$env:OURA_CLIENT_SECRET = "<your-client-secret>"
oura-mcp login              # or: dnx -y gjlumsden.OuraMcp -- login

Tokens are saved to ~/.oura-mcp/tokens.json; subsequent server launches will skip the browser prompt. You can also pass --no-login to oura-mcp to suppress the auto-login prompt on startup (useful if tokens are provisioned out-of-band).

3. Start Using

Once configured, your MCP client will discover the Oura tools automatically. Try prompts like:

"How did I sleep last night?"
"Show my readiness score for the past week"
"What was my resting heart rate trend this month?"
"Compare my deep sleep vs REM sleep over the last 2 weeks"
"What's my VO2 max and cardiovascular age?"
"How stressed was I this week?"
"Show my SpO2 trends — anything concerning?"
"When did I work out this week and how many calories did I burn?"

Combining with Other MCP Tools

The real power comes from combining Oura data with other MCP servers. For example, with WorkIQ (Microsoft 365 Copilot):

"Look at my meetings last week and correlate with my stress levels"
"Which days did I have the most meetings? How did that affect my sleep?"
"I had a stressful Friday — what meetings were in my calendar that day?"
"Compare my readiness scores on meeting-heavy days vs focus days"

With the Azure MCP Server:

"I'm on-call this week — show my sleep quality and readiness so I know if I'm fit for incident response"

With GitHub MCP:

"Show my commit activity alongside my daily activity scores — am I coding more on high-energy days?"

Any MCP-compatible tool can be combined — the AI assistant joins the dots across data sources automatically.

Available Tools

Tool	Description
`get_personal_info`	Retrieves personal info from the Oura Ring account.
`get_ring_configuration`	Retrieves ring configuration details from the Oura Ring.
`get_daily_sleep`	Retrieves daily sleep scores and summaries from the Oura Ring.
`get_sleep_periods`	Retrieves detailed sleep period data from the Oura Ring.
`get_sleep_time`	Retrieves recommended sleep time windows from the Oura Ring.
`get_daily_activity`	Retrieves daily activity scores and step counts from the Oura Ring.
`get_workouts`	Retrieves workout data from the Oura Ring.
`get_sessions`	Retrieves session data such as meditation and breathing exercises from the Oura Ring.
`get_daily_readiness`	Retrieves daily readiness scores from the Oura Ring.
`get_daily_stress`	Retrieves daily stress data from the Oura Ring.
`get_daily_resilience`	Retrieves daily resilience data from the Oura Ring.
`get_rest_mode_periods`	Retrieves rest mode period data from the Oura Ring.
`get_heart_rate`	Retrieves heart rate data from the Oura Ring.
`get_daily_spo2`	Retrieves daily SpO2 blood oxygen data from the Oura Ring.
`get_vo2_max`	Retrieves VO2 max estimates from the Oura Ring.
`get_cardiovascular_age`	Retrieves cardiovascular age estimates from the Oura Ring.
`get_tags`	Retrieves tags from the Oura Ring.
`get_enhanced_tags`	Retrieves enhanced tags from the Oura Ring.

Most date-range tools accept optional startDate and endDate parameters (format: YYYY-MM-DD).

Note: HRV (heart rate variability) data is embedded in the get_sleep_periods response — there is no separate HRV endpoint in the Oura API v2.

Authentication Flow

This server uses an az login-style OAuth authentication pattern, similar to the Azure MCP Server, integrated into the main MCP experience:

Automatic first launch: When the server starts and no tokens are present, it opens your browser to the Oura OAuth consent screen as part of its normal startup — no separate command is required. Pass --no-login to suppress this behavior if you provision tokens out-of-band.
Explicit login (optional): You can still run oura-mcp login (or dnx -y gjlumsden.OuraMcp -- login for the no-install option, or dotnet run --project src/OuraMcp -- login from source) to authenticate ahead of time (e.g., headless setup, CI).
Token exchange: After you authorize, a local callback server on http://localhost:8742/callback/ receives the authorization code and exchanges it for access/refresh tokens.
Persistent storage: Tokens are saved to ~/.oura-mcp/tokens.json (file permissions restricted to owner on Unix).
Automatic refresh: On subsequent startups the server loads saved tokens and refreshes them automatically when expired.

OAuth credentials (OURA_CLIENT_ID, OURA_CLIENT_SECRET) are read from environment variables — never stored in source.

Headless / CI: `OURA_MCP_DISABLE_BROWSER`

For fully headless environments (CI agents, containers without a display) you can set the OURA_MCP_DISABLE_BROWSER environment variable. When set:

The server skips launching the system browser and skips binding the local OAuth callback listener on http://localhost:8742/callback/.
The interactive login flow cannot complete in this mode, so the server fails fast with a clear error rather than hanging waiting for a callback.

Pair OURA_MCP_DISABLE_BROWSER with --no-login and provision tokens out-of-band (e.g., copy a tokens.json produced on another machine into the token directory). To run the interactive oura-mcp login flow, leave OURA_MCP_DISABLE_BROWSER unset.

Development

To contribute or run from source:

git clone https://github.com/gjlumsden/oura-mcp.git
cd oura-mcp
dotnet build
dotnet test

# Set OAuth credentials
$env:OURA_CLIENT_ID = "<your-client-id>"
$env:OURA_CLIENT_SECRET = "<your-client-secret>"

# Run the MCP server locally (STDIO) — opens the browser automatically on first launch
dotnet run --project src/OuraMcp

# Or authenticate explicitly first (optional; useful for headless scenarios)
dotnet run --project src/OuraMcp -- login

Caching

The server includes in-memory caching to reduce redundant Oura API calls within a session. When an AI assistant calls the same tool with the same parameters, cached data is returned instead of hitting the API again.

Cache is in-memory only — it's cleared automatically when the server process restarts. Different date ranges are cached independently.

TTL	Endpoints	Rationale
60 min	Personal info, ring configuration	Rarely changes
15 min	Sleep, readiness, sleep periods, sleep time	Can change (e.g., naps) but not often
10 min	Activity, stress, resilience, workouts, sessions, SpO2, VO2 max, cardiovascular age, tags, rest mode	Day-anchored data that stabilises after logging
1 min	Heart rate	High-frequency streaming data

Resilience

All Oura API requests are protected by a standard resilience pipeline powered by Polly via Microsoft.Extensions.Http.Resilience:

Strategy	Configuration	Purpose
Retry	3 attempts, exponential backoff + jitter	Handles 429 (rate limit), 500+, 408, and network errors
Circuit breaker	Opens at 10% failure rate, 5s break	Prevents hammering a failing API
Attempt timeout	10s per request	Caps individual request duration
Total timeout	30s including retries	Caps end-to-end request duration

The resilience handler respects Retry-After headers from rate-limited responses. Auth errors (401) and permission errors (403) are handled separately by the client and are not retried.

Technology Stack

.NET 10 / C# with nullable reference types
ModelContextProtocol NuGet package (MCP C# SDK) — STDIO transport
System.Text.Json for serialization
IHttpClientFactory for HTTP client lifecycle management
IMemoryCache for in-memory response caching with tiered TTLs
Microsoft.Extensions.Http.Resilience (Polly) for retry, circuit breaker, and timeout policies

License

MIT