io.github.jordanburke/oura-ring-mcp-server

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.

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