Oura MCP Server

A Model Context Protocol (MCP) server for accessing Oura Ring data.

It runs in two modes from the same codebase:

Mode	Entrypoint	Transport	Use it for
Local	npm run start:stdio	stdio	Claude Code and Claude Desktop on your own machine
Hosted	npm start	Streamable HTTP + OAuth	claude.ai in the browser and the Claude mobile apps

Prerequisites

• Node.js 20+
• An Oura account

Installation

npm install
npm run build

Oura credentials

1. Log in to the Oura Cloud Console
2. Create a Personal Access Token

Set it as OURA_PERSONAL_ACCESS_TOKEN. See .env.example for the full list of variables. Set OURA_TIMEZONE to your IANA zone (e.g. America/Phoenix) — it decides what "the last 7 days" means for the resource defaults. It falls back to UTC, which shifts the window by a day for part of every day anywhere west of Greenwich, so it is worth setting explicitly.

Personal access tokens are the only supported credential. Earlier versions also accepted OAuth2 client id/secret, but nothing ever ran the authorization-code flow against Oura, so that path could only fail at request time; it has been removed rather than left as a trap.

---

Local mode (stdio)

Claude Code

claude mcp add oura -s user \
  -e OURA_PERSONAL_ACCESS_TOKEN=your_token \
  -- "$(command -v node)" /absolute/path/to/oura-mcp/build/index.js

Claude Desktop

Settings → Developer → Edit Config:

{
  "mcpServers": {
    "oura": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/oura-mcp/build/index.js"],
      "env": { "OURA_PERSONAL_ACCESS_TOKEN": "your_token" }
    }
  }
}

Pass the token in env rather than relying on a .env file. dotenv resolves .env against the current working directory, which for a client-launched server is wherever the client happened to start — not this repo.

Testing

npm test        # builds first, then runs the suite

22 tests across two suites, none of which need a live Oura token: oauth.test.ts drives the real OAuth flow over HTTP (discovery, dynamic registration, PKCE, single-use codes, refresh, bearer rejection), and tools.test.ts checks the tool and resource surface over stdio — including a regression test that stdout carries nothing but JSON-RPC.

For a manual probe against real data:

node test.js get_daily_sleep 2026-08-01

---

Hosted mode (HTTP + OAuth)

claude.ai and the mobile apps only talk to remote MCP servers over HTTPS, so reaching your data from a phone means deploying this somewhere.

What the auth actually does

The server is its own OAuth 2.1 authorization server. Your Oura token stays in server-side env and is never handed to the client; the OAuth flow exists only to prove that whoever is calling /mcp knows MCP_AUTH_PASSWORD.

Client ids, authorization codes, and tokens are all HMAC-signed payloads rather than database rows, so a redeploy doesn't sign you out and no storage needs provisioning. Clients are registered as public clients and authenticate with PKCE. Authorization codes are single-use.

Deploying to Railway

1. Create a new Railway project from this repo. railway.json pins the build and start commands and points the healthcheck at /healthz.

2. Generate a signing secret:

   openssl rand -hex 32
   

3. Set these variables in the Railway service:

   Variable	Value
   OURA_PERSONAL_ACCESS_TOKEN	your Oura token
   OAUTH_SIGNING_SECRET	the hex string from step 2
   MCP_AUTH_PASSWORD	the password you'll type when connecting

   You do not need to set PUBLIC_URL on Railway. The server falls back to RAILWAY_PUBLIC_DOMAIN, which Railway injects once the service has a domain (Settings → Networking → Public Networking → Generate Domain). Set PUBLIC_URL explicitly only when hosting elsewhere, or to override the advertised origin — it must then match the real origin exactly, since it's what the server publishes in its OAuth metadata.

4. Confirm the deploy: curl https://your-app.up.railway.app/healthz

PORT is injected by Railway; don't set it yourself.

Connecting Claude

In claude.ai → Settings → Connectors → Add custom connector, use:

https://your-app.up.railway.app/mcp

Leave the OAuth client fields blank — the server supports dynamic client registration, so Claude registers itself. You'll be redirected to a sign-in page asking for MCP_AUTH_PASSWORD, and after that the connector is available in the browser and on the mobile apps under the same account.

Endpoints

Path	Purpose
POST /mcp	The MCP endpoint. Requires a bearer token and the oura:read scope.
/authorize, /token, /register, /revoke	OAuth, mounted by the MCP SDK
POST /login	Password form posted from the authorize page
/.well-known/oauth-authorization-server	AS metadata
/.well-known/oauth-protected-resource/mcp	Protected-resource metadata
GET /healthz	Healthcheck

GET and DELETE on /mcp return 405: the server runs the transport in stateless mode, so there's no long-lived SSE stream or session to tear down. Every request gets a fresh server instance, which is what lets a redeploy or a second replica pick up mid-conversation.

---

Available resources

personal_info, daily_activity, daily_readiness, daily_sleep, sleep, sleep_time, workout, session, daily_spo2, rest_mode_period, ring_configuration, daily_stress, daily_resilience, daily_cardiovascular_age, vO2_max

Date-based resources default to the last 7 days, bounded by OURA_TIMEZONE.

Response shape

Results are paginated by Oura via next_token; the server follows it to completion, so a wide date range returns every record rather than the first page. It stops after 25 pages and marks the response truncated rather than looping.

Interval-sample fields — the per-30-second and per-5-minute arrays on sleep (heart_rate, hrv, movement_30_sec, sleep_phase_5_min) and daily_activity (class_5_min, met) — are stripped by default, since a month of them runs to megabytes and crowds out the conversation. Pass includeIntervalSamples: true on a narrow range when you need them.

Available tools

Every date-based resource above has a matching get_<name> tool taking startDate and endDate in YYYY-MM-DD form — 13 in total.