oura-mcp-server

A personal MCP (Model Context Protocol) server that exposes your own Oura Ring data — sleep, readiness, activity, heart rate, workouts, tags — as tools Claude Desktop or Claude Code can call directly.

Important scope note: this only works with Claude Desktop or Claude Code, which can launch local MCP servers as subprocesses. It does not work with claude.ai in a browser or the mobile app — those can only use hosted (remote) connectors, and there is no first-party hosted Oura connector from Anthropic as of this writing.

Also important: Oura deprecated Personal Access Tokens in December 2025. The old "generate a token in your account settings and paste it into a script" shortcut you may see in older blog posts no longer works. This server uses the full OAuth2 flow, which is now mandatory even for pulling just your own data.

---

Using this if you didn't write it

This repo is a template, not a shared service — there's no account or data tied to it. If you're setting this up for yourself:

• Register your own OAuth application in step 1 below. Don't reuse someone else's Client ID/Secret — each person needs their own app registration, since Oura ties API access to the app that requests it.
• Everything stays local to your machine. Your .env (Client ID/Secret) and ~/.oura-mcp/tokens.json (access/refresh tokens) are created fresh when you run through the setup steps, are gitignored, and are never read from or written to this repo. Cloning this code gives you the program, not anyone's credentials or health data.
• You authorize your own Oura account in step 3 — the OAuth login screen is Oura's, not this project's, so you're logging into (and granting access to) your own account only.
• Per Oura's API agreement, personal use to access your own data is fine, but the data can't be cached/stored beyond what's needed to serve a request, shared with third parties, or used to train/fine-tune an AI model. This server already follows that: it fetches data live on each tool call and never writes API responses to disk (only OAuth tokens are persisted, which is required for auth).

---

What this gives you

10 MCP tools:

Tool	What it returns
oura_get_daily_sleep	Daily sleep score + contributors (REM, deep, efficiency, restfulness)
oura_get_daily_readiness	Daily readiness score + contributors (HRV balance, resting HR, recovery index)
oura_get_daily_activity	Daily activity score, steps, active calories
oura_get_daily_spo2	Nightly average blood oxygen saturation
oura_get_sleep_periods	Raw per-sleep-period data: actual HRV average, lowest/avg HR during sleep, stage durations, bedtime start/end
oura_get_heartrate	Raw 5-minute-resolution heart rate time series between two datetimes
oura_get_workouts	Logged/auto-detected workouts: type, duration, calories, intensity
oura_get_tags	User-entered tags/notes (e.g. "alcohol", "illness")
oura_get_personal_info	Age, weight, height, biological sex on file with Oura
oura_call_endpoint	Escape hatch for any other usercollection/* endpoint (e.g. usercollection/rest_mode_period, usercollection/ring_configuration) not covered above

The escape-hatch tool and every other tool are hard-restricted to read-only usercollection/* paths — the server refuses to call webhook/* (subscription management) or anything else, so there's no path for this to accidentally do anything beyond reading your own data.

Tokens auto-refresh. You authorize once; after that, npm start just works until you manually revoke access on Oura's side.

---

1. Register an Oura OAuth application (one-time, ~2 minutes)

1. Go to https://cloud.ouraring.com/oauth/applications and sign in with your Oura account.
2. Create a new application. Name/website can be anything descriptive ("Personal MCP server" is fine).
3. Set the redirect URI to exactly:

   http://localhost:8734/callback
   

   (If you want a different port, change OURA_AUTH_PORT in .env and update the redirect URI here to match — they must be identical.)
4. Copy the Client ID and Client Secret it gives you.

2. Install and configure

git clone https://github.com/BarnNorth/oura-mcp-server.git
cd oura-mcp-server
npm install
cp .env.example .env

Edit .env and paste in your Client ID and Client Secret:

OURA_CLIENT_ID=your_client_id_here
OURA_CLIENT_SECRET=your_client_secret_here

3. Run the one-time authorization

npm run authorize

This prints a URL — open it in your browser, log into Oura, and approve the requested scopes. The script catches the redirect automatically, exchanges the code for tokens, and saves them to ~/.oura-mcp/tokens.json (permissions locked to your user only, chmod 600). You only need to do this once; after that the server refreshes tokens on its own.

If you ever see an error about a revoked or invalid refresh token, just re-run npm run authorize.

4. Point Claude Desktop at the server

Open (or create) Claude Desktop's config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add an entry under mcpServers (merge with whatever's already there — don't replace the whole file if you have other servers configured):

{
  "mcpServers": {
    "oura": {
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/oura-mcp-server/.env",
        "/absolute/path/to/oura-mcp-server/src/server.js"
      ]
    }
  }
}

Use absolute paths on your machine — relative paths won't resolve correctly since Claude Desktop launches it as a subprocess from its own working directory. The --env-file flag is required here: unlike npm run start, Claude Desktop invokes node directly, so nothing else loads .env into the process.

Fully quit and reopen Claude Desktop (not just close the window — Cmd+Q on macOS, or quit from the system tray on Windows). Start a new conversation; you should see a tools/hammer icon indicating the server connected, and you can ask things like "pull my Oura readiness for the last 7 days."

For Claude Code, the equivalent is a project-level .mcp.json:

{
  "mcpServers": {
    "oura": {
      "type": "stdio",
      "command": "node",
      "args": [
        "--env-file=/absolute/path/to/oura-mcp-server/.env",
        "/absolute/path/to/oura-mcp-server/src/server.js"
      ]
    }
  }
}

---

Security notes (read this once)

• Your Client Secret and tokens never leave your machine — everything runs as a local subprocess talking directly to api.ouraring.com. There's no third party in the middle.
• .env and ~/.oura-mcp/tokens.json are both in .gitignore. If you ever put this project in a git repo (recommended, since it's your own code), double check those never get committed.
• The server only requests read scopes and only calls usercollection/* read endpoints — it cannot modify your Oura data, delete anything, or manage webhook subscriptions on your account.
• Rate limit is 5,000 requests / 5 minutes per Oura's v2 API — you will not come close to this with normal conversational use.

Troubleshooting

• "No stored Oura tokens found" — run npm run authorize before npm start.
• 401 after refresh — the refresh token was revoked (e.g. you removed the app's access in your Oura account settings). Re-run npm run authorize.
• 403 Forbidden — either the granted scope doesn't cover that endpoint, or your Oura membership has lapsed (Oura requires an active membership for API access on Gen3+ rings).
• Claude Desktop doesn't show the tools — check the exact JSON syntax (a stray comma breaks the whole config file silently), confirm the path in args is absolute, and check Claude's MCP logs (macOS: ~/Library/Logs/Claude/).