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

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

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