ouraring-mcp

MCP (Model Context Protocol) server that lets an AI assistant read your own Oura Ring data — sleep, readiness, activity, heart rate, SpO2, stress, workouts, sessions — so you can ask questions and get summaries in natural language. Personal, single-user, non-commercial use. Data is fetched on demand and not stored or shared.

Built for the Oura API v2 (api.ouraring.com), same stdio-MCP layout as parksapi-mcp.

Tools

All tools return JSON as text and are read-only. Unknown collections/types return { isError: true } with a plain message, never a protocol error. Date params are YYYY-MM-DD; heartrate also accepts ISO datetimes + latest.

Related MCP server: Oura Ring MCP Server

Requirements

Node 22+.

Setup

npm install
npm run build

OAuth2 (only method — Oura retired PATs Dec 2025)

Register at https://cloud.ouraring.com/oauth/applications with:

• Redirect URI: http://localhost:8080/callback

• Scopes: email personal daily heartrate workout tag session spo2 ring_configuration stress heart_health

• Privacy / Terms: this repo's PRIVACY.md / TERMS.md

Then:

npm run auth:oura       # prints the authorize URL
# open the URL, approve, copy ?code= from the localhost redirect, then:
npm run auth:oura -- --code=PASTE_CODE_HERE

auth:oura reads OURARING_CLIENT_ID/OURARING_CLIENT_SECRET from the environment → local .env → ~/.hermes/.env, then prints OURARING_ACCESS_TOKEN (short-lived) + OURARING_REFRESH_TOKEN (long-lived). The server auto-refreshes via the refresh token when client credentials are present — no manual refresh needed.

Install in your tools

Build once (npm install && npm run build), then point any client at dist/index.js via stdio with OURARING_REFRESH_TOKEN + OURARING_CLIENT_ID + OURARING_CLIENT_SECRET in the environment (server auto-refreshes; access token alone expira rápido). Replace /path/to/ouraring-mcp with your checkout below.

Claude Code

claude mcp add ouraring \
  --env OURARING_REFRESH_TOKEN=... \
  --env OURARING_CLIENT_ID=... \
  --env OURARING_CLIENT_SECRET=... \
  -- node /path/to/ouraring-mcp/dist/index.js

Or per-project .mcp.json (user scope: claude mcp add -s user ...):

{
  "mcpServers": {
    "ouraring": {
      "command": "node",
      "args": ["/path/to/ouraring-mcp/dist/index.js"],
      "env": {
        "OURARING_REFRESH_TOKEN": "...",
        "OURARING_CLIENT_ID": "...",
        "OURARING_CLIENT_SECRET": "..."
      }
    }
  }
}

Codex CLI (~/.codex/config.toml)

[mcp_servers.ouraring]
command = "node"
args = ["/path/to/ouraring-mcp/dist/index.js"]

[mcp_servers.ouraring.env]
OURARING_REFRESH_TOKEN = "..."
OURARING_CLIENT_ID = "..."
OURARING_CLIENT_SECRET = "..."

OpenCode

opencode mcp add ouraring \
  --env OURARING_REFRESH_TOKEN=... \
  --env OURARING_CLIENT_ID=... \
  --env OURARING_CLIENT_SECRET=... \
  -- node /path/to/ouraring-mcp/dist/index.js

Config-file equivalent (opencode.jsonc; v2 nests under mcp.servers, older versions use flat mcp):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "ouraring": {
        "type": "local",
        "command": ["node", "/path/to/ouraring-mcp/dist/index.js"],
        "environment": {
          "OURARING_REFRESH_TOKEN": "...",
          "OURARING_CLIENT_ID": "...",
          "OURARING_CLIENT_SECRET": "..."
        }
      }
    }
  }
}

Hermes (~/.hermes/config.yaml)

mcp_servers:
  ouraring:
    command: node
    args:
      - /home/hermes/github/ouraring-mcp/dist/index.js
    env:
      OURARING_REFRESH_TOKEN: "..."
      OURARING_CLIENT_ID: "..."
      OURARING_CLIENT_SECRET: "..."
    enabled: true

Then restart the gateway. Verify with oura_status (no network call).

OpenClaw

openclaw mcp add ouraring \
  --cwd /path/to/ouraring-mcp \
  -- command node --arg /path/to/ouraring-mcp/dist/index.js
openclaw mcp doctor ouraring --probe

Set the tokens via Settings → MCP (scoped config editor → environment values), or OURARING_REFRESH_TOKEN + client credentials in the gateway environment.

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "ouraring": {
      "command": "node",
      "args": ["/path/to/ouraring-mcp/dist/index.js"],
      "env": {
        "OURARING_REFRESH_TOKEN": "...",
        "OURARING_CLIENT_ID": "...",
        "OURARING_CLIENT_SECRET": "..."
      }
    }
  }
}

Examples

{ "data_type": "sleep", "start_date": "2026-10-15", "end_date": "2026-10-22" }
{ "collection": "heartrate", "start_datetime": "2026-10-22T00:00:00Z", "latest": true }
{ "collection": "ring_battery_level", "start_datetime": "2026-10-21T00:00:00-04:00" }
{ "collection": "workout", "start_date": "2026-10-01", "end_date": "2026-10-22", "fields": "activity_type,calories" }
{ "collection": "VO2_Max", "start_date": "2026-09-22", "end_date": "2026-10-22" }
{ "days": 7 }

Notes (checked against Oura's OpenAPI spec):

• Collection names are case-insensitive, but the API path for VO₂max is case-sensitive upstream (vO2_max) — the server maps it automatically.

• heartrate and ring_battery_level query by ISO datetime + latest; ring_configuration takes no date params; everything else takes start_date/end_date. Single-doc fetch via document_id only where the API offers it (not for enhanced_tag/heartrate/personal_info/ring_battery_level).

• fields selects response fields on most routes (not daily_resilience, enhanced_tag, tag).

• Webhooks (/v2/webhook/*) are out of scope: they need a public HTTPS URL and write operations — this server is read-only by design.

Privacy

See PRIVACY.md and TERMS.md: on-demand reads only, no sharing, single user. Revoke any time from your Oura dashboard.

Cold cache

Repeat date-range queries don't re-hit Oura: responses are cached in ./oura-cache.sqlite (node:sqlite, git-ignored — never committed) with per-day coverage. The last 2 days always refetch (Oura keeps finalizing them); older days are immutable — fetched once, served forever. Range queries that end in the past and are fully covered use zero upstream calls (cacheHit: true in the response). personal_info / ring_configuration are cached 30 days, single-document fetches 7 days. Any SQLite error disables the cache silently and the call goes straight to the API.

OURARING_CACHE_PATH=/tmp/oura.sqlite   # default ./oura-cache.sqlite
OURARING_CACHE_ENABLED=0               # bypass cache, fail-soft
OURARING_PERSONAL_INFO_TTL_HOURS=720   # default 30d
OURARING_RING_CONFIGURATION_TTL_HOURS=720
OURARING_CACHE_TTL_HOURS=168           # default 7d for the rest

(OURA_* aliases work for every knob above.)

Develop

npm test   # build + vitest (offline unit, stdio protocol, opt-in live)
npm audit --audit-level=moderate   # fail on moderate+ advisories (dev + prod deps)

tests/live.test.ts calls the real API only when OURARING_ACCESS_TOKEN is set; otherwise it passes with a skip note.

Every push is gated: npm run setup:hooks installs a pre-push hook that rebuilds and runs the suite — a red test blocks the push. GitHub Actions (.github/workflows/ci.yml) enforces the same on every push/PR, plus npm audit (moderate+) so new advisories break the build before merge. Dependency upgrades that fix audit findings must keep the suite green (e.g. vitest 3 → 5); if a fix needs a breaking major, do it in its own commit with the audit delta in the message.