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>"
      }
    }
  }
}

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>"
      }
    }
  }
}

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

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:

1. 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.
2. 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).
3. 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.
4. Persistent storage: Tokens are saved to ~/.oura-mcp/tokens.json (file permissions restricted to owner on Unix).
5. 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.

Resilience

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

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