Oura MCP Server

An MCP server that connects your Oura Ring to Claude and other AI assistants. Get human-readable insights about your sleep, readiness, and activity—not just raw JSON.

Features

<img src="docs/outputs/demo.gif" width="500" alt="Demo">

• Smart formatting - Durations in hours/minutes, scores with context ("85 - Optimal")
• Sleep analysis - Sleep stages, efficiency, HRV, and biometrics
• Readiness tracking - Recovery scores and contributor breakdown
• Activity data - Steps, calories, and intensity breakdown
• Health metrics - Heart rate, SpO2, stress, cardiovascular age
• Smart analysis - Anomaly detection, correlations, trend analysis
• Tags support - Compare metrics with/without conditions

See example outputs — what Claude returns for sleep, readiness, weekly summaries, and smart analysis

Quick Start

1. Install

npm install -g oura-ring-mcp

Or use directly with npx (no install needed):

npx oura-ring-mcp

2. Authenticate with Oura

Option A: Personal Access Token (simpler)

1. Go to cloud.ouraring.com/personal-access-tokens
2. Create a new token
3. Set OURA_ACCESS_TOKEN in your Claude Desktop config (see below)

Option B: OAuth CLI Flow

1. Create an OAuth app at developer.ouraring.com

• Set Redirect URI to http://localhost:3000/callback

1. Run the auth flow:

   export OURA_CLIENT_ID=your_client_id
   export OURA_CLIENT_SECRET=your_client_secret
   npx oura-ring-mcp auth

1. Credentials are saved to ~/.oura-mcp/credentials.json

3. Configure Claude Desktop

Add to claude_desktop_config.json:

With Personal Access Token:

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["oura-ring-mcp"],
      "env": {
        "OURA_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

With OAuth (after running `npx oura-ring-mcp auth`):

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["oura-ring-mcp"]
    }
  }
}

The server reads credentials from ~/.oura-mcp/credentials.json. To enable automatic token refresh, add your OAuth credentials:

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["oura-ring-mcp"],
      "env": {
        "OURA_CLIENT_ID": "your_client_id",
        "OURA_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

Restart Claude Desktop. Requires Node >=18.

What Can I Ask?

Daily check-ins:

• "How did I sleep last night?"
• "Am I recovered enough to work out today?"
• "What's my body telling me right now?"

Patterns & trends:

• "Do I sleep better on weekends?"
• "What time should I go to bed for optimal sleep?"
• "Is my HRV improving or declining?"

Correlations & insights:

• "Does alcohol affect my sleep quality?"
• "What predicts my best sleep nights?"
• "How does exercise timing affect my recovery?"

Comparisons:

• "Compare my sleep this week vs last week"
• "How do I sleep after meditation vs without?"
• "What changed when I started taking magnesium?"

Anomalies:

• "Are there any unusual readings in my data?"
• "Why was my readiness so low yesterday?"
• "Find days where my metrics were off"

Available Tools

Data Retrieval

Smart Analysis

Resources

Prompts

Remote Deployment (Railway)

Deploy the MCP server for remote access. The server proxies OAuth through Oura, so users authenticate directly with their Oura account — no PAT needed.

1. Create an Oura OAuth App

1. Go to Oura OAuth Applications
2. Create a new application
3. Set the Redirect URI to: https://your-app.railway.app/oauth/callback
4. Note the Client ID and Client Secret

2. Deploy

# Install Railway CLI
npm install -g @railway/cli

# Login, init, and deploy
railway login
railway init
railway up

3. Set Environment Variables

In the Railway dashboard, add:

Railway automatically sets PORT and RAILWAY_PUBLIC_DOMAIN.

4. Connect from Claude.ai

Use the connector in Claude.ai:

1. Go to Settings > MCP Connectors > Add
2. Enter your server URL: https://your-app.railway.app (without /mcp)
3. Leave OAuth Client ID and Secret empty (dynamic registration handles it)
4. You'll be redirected to Oura to authorize access to your data

5. Connect from Claude Desktop

For Claude Desktop, use MCP_SECRET + OURA_ACCESS_TOKEN:

{
  "mcpServers": {
    "oura-remote": {
      "url": "https://your-app.railway.app/mcp",
      "headers": {
        "Authorization": "Bearer your_mcp_secret_here"
      }
    }
  }
}

Local Testing

# With Oura OAuth (full flow)
OURA_CLIENT_ID=your_id OURA_CLIENT_SECRET=your_secret pnpm start:http

# With static secret only (requires OURA_ACCESS_TOKEN)
OURA_ACCESS_TOKEN=your_pat MCP_SECRET=test-secret pnpm start:http

# Verify health endpoint
curl http://localhost:3000/health

# Check OAuth metadata (only available when OURA_CLIENT_ID is set)
curl http://localhost:3000/.well-known/oauth-authorization-server

# Test authenticated request (with static secret)
curl -X POST http://localhost:3000/mcp \
  -H "Authorization: Bearer test-secret" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"capabilities":{}},"id":1}'

Contributing

See CLAUDE.md for architecture details and development guidelines.

License

MIT