oura-mcp

A CLI and MCP server for the Oura Ring API v2. Query sleep, readiness, activity, heart rate, stress, SpO2, workouts, and session data from the command line or through Claude Code / any MCP client.

Features

• CLI: Query all Oura data for any date
• MCP Server: 10 tools for integration with Claude Code and other MCP clients
• Auth: Supports both personal access tokens and OAuth2 with automatic token refresh

MCP Tools

Tool	Description
oura_daily_summary	Sleep score, readiness score, sleep details, and activity for a date
oura_sleep	Detailed sleep session data (duration, stages, HR, HRV)
oura_readiness	Readiness score and contributors
oura_activity	Daily activity data (steps, calories, distance)
oura_workouts	Auto-detected workouts with HR, calories, duration, and intensity
oura_heart_rate	Continuous heart rate data for a time window
oura_stress	Daily stress and recovery levels
oura_spo2	Blood oxygen (SpO2) percentage
oura_sessions	Meditation, breathing, and relaxation sessions
oura_trends	Multi-day sleep and readiness score trends

Install as Claude Code Plugin

claude plugin marketplace add daveremy/oura-mcp
claude plugin install oura-mcp@oura-mcp-plugins

Then set your Oura token in the plugin's env (see Auth below).

Setup

1. Get an Oura API Token

Personal Access Token (simplest):

1. Go to the Oura Developer Portal
2. Create a new personal access token
3. Save it: npx @daveremy/oura-mcp config set-token YOUR_TOKEN

The token is stored at ~/.oura-mcp/config.json and works everywhere — CLI, MCP server, and Claude Code plugin. You can also set OURA_TOKEN as an environment variable (takes precedence over stored config).

OAuth2 (for automatic token refresh):

1. Create an app at Oura OAuth Applications
2. Set redirect URI to http://localhost:9876/callback
3. Set OURA_CLIENT_ID and OURA_CLIENT_SECRET in your environment
4. Run oura auth to complete the flow

2. Use as MCP Server

No install needed — use npx to run directly:

{
  "mcpServers": {
    "oura": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@daveremy/oura-mcp"],
      "env": {
        "OURA_TOKEN": "your_token"
      }
    }
  }
}

Or register via CLI:

claude mcp add oura -- npx -y @daveremy/oura-mcp

3. Use as CLI

npm install -g @daveremy/oura-mcp
export OURA_TOKEN=your_token

oura sleep                    # Today's sleep data
oura sleep --date 2026-03-05  # Specific date
oura readiness                # Today's readiness
oura activity                 # Today's activity
oura workouts                 # Today's workouts
oura stress                   # Today's stress levels
oura spo2                     # Today's blood oxygen
oura sessions                 # Today's meditation/breathing sessions
oura heart-rate --start 2026-03-05T08:00:00 --end 2026-03-05T09:00:00
oura summary                  # Everything for today
oura config set-token <tok>   # Save token to ~/.oura-mcp/config.json
oura config show              # Show stored config (masked)
oura config clear             # Remove stored credentials

All commands output JSON to stdout.

4. Install from source

git clone https://github.com/daveremy/oura-mcp.git
cd oura-mcp
npm install
npm run build

Environment Variables

Variable	Required	Description
OURA_TOKEN	Option A	Personal access token (simplest)
OURA_ACCESS_TOKEN	Option B	OAuth2 access token
OURA_REFRESH_TOKEN	Option B	OAuth2 refresh token
OURA_CLIENT_ID	Option B	OAuth2 client ID
OURA_CLIENT_SECRET	Option B	OAuth2 client secret

Skills

This plugin bundles a /oura skill for conversational health data queries:

/oura              # Today's health briefing
/oura sleep        # Detailed sleep data
/oura readiness    # Readiness score and contributors
/oura activity     # Steps, calories, distance
/oura workouts     # Auto-detected workouts
/oura hr <start> <end>  # Heart rate for a time window
/oura stress       # Stress and recovery levels
/oura spo2         # Blood oxygen
/oura sessions     # Meditation/breathing sessions
/oura trends       # 7-day sleep + readiness trends
/oura trends 14    # 14-day trends
/oura summary      # Full daily summary (same as default)

The skill orchestrates the MCP tools into conversational, insight-driven responses instead of raw JSON.

Requirements

• Node.js 18+
• An Oura Ring with API access

License

MIT