oura-mcp

A self-hostable MCP server that exposes your Oura Ring health data as tools for Claude and other MCP-compatible clients. Ask about your sleep, readiness, activity, and heart rate in natural language — the MCP server handles the API calls and returns structured data that AI assistants can reason about.

Designed to run in Docker on home lab infrastructure (e.g. Proxmox), or locally for development.

Why?

MCP (Model Context Protocol) lets AI assistants call external tools. This server turns your Oura Ring into one of those tools. Instead of opening the Oura app, you can ask Claude:

"How did I sleep last night?"
"Give me a morning health briefing"
"Compare my readiness scores for the past week"
"What's my HRV trend over the last 5 days?"

Architecture

┌─────────────────┐       MCP Protocol        ┌─────────────┐      HTTPS       ┌─────────────┐
│  Claude Desktop  │◄─────(stdio or HTTP)─────►│  oura-mcp   │◄────────────────►│  Oura API   │
│  or MCP Client   │                           │  server      │  Bearer token    │  v2          │
└─────────────────┘                            └─────────────┘                  └─────────────┘

Transports supported:

stdio — Claude Desktop launches the server as a subprocess (recommended for desktop use)
Streamable HTTP — server runs standalone on port 3333 at /mcp (recommended for Docker / remote access)

Project structure:

src/
  index.ts              Entry point — transport setup, tool registration
  oura-client.ts        All Oura API HTTP calls (centralized)
  utils/
    date.ts             Date resolution ("today", "yesterday", "YYYY-MM-DD")
  tools/
    sleep.ts            get_sleep
    readiness.ts        get_readiness
    activity.ts         get_activity
    heart-rate.ts       get_heart_rate
    summary.ts          get_daily_summary

Prerequisites

Node.js 20+ (for local development) or Docker (for containerized deployment)
Oura personal access token — see Getting your token

Quick Start

Docker (recommended for self-hosting)

git clone https://github.com/IcePoint810/oura-mcp.git
cd oura-mcp
cp .env.example .env        # edit and add your token
docker compose up -d

Local development

git clone https://github.com/IcePoint810/oura-mcp.git
cd oura-mcp
npm install
cp .env.example .env        # edit and add your token
OURA_TOKEN=your_token npm run dev

Getting Your Oura Token

Go to cloud.ouraring.com and sign in
Navigate to Personal Access Tokens in your account settings
Create a new token and copy it
Paste it into your .env file or pass it as an environment variable

Connecting to Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option A: stdio (recommended)

Claude Desktop launches the server automatically — no separate process needed.

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["tsx", "/path/to/oura-mcp/src/index.ts", "--stdio"],
      "env": {
        "OURA_TOKEN": "your_token_here"
      }
    }
  }
}

Option B: Streamable HTTP (remote / Docker)

Start the server first (docker compose up -d or npm run dev), then:

{
  "mcpServers": {
    "oura": {
      "url": "http://localhost:3333/mcp"
    }
  }
}

After editing the config, restart Claude Desktop.

Available Tools

| Tool | Description | Inputs | |------|-------------|--------| | get_sleep | Sleep score, duration, stages (REM/deep/light/awake), HRV, breath rate, lowest HR, bedtime | date, start_date, end_date | | get_readiness | Readiness score + 8 contributing factors (HRV balance, body temp, recovery, etc.) | date, start_date, end_date | | get_activity | Steps, calories, activity minutes (high/medium/low), distance, inactivity alerts | date, start_date, end_date | | get_heart_rate | Average/min resting HR, HRV trend direction (multi-day only) | date, start_date, end_date | | get_daily_summary | Combined highlights from sleep + readiness + activity with notable flags | date |

All date inputs accept "today", "yesterday", or "YYYY-MM-DD". Default: yesterday.

Example Interaction

You: How did I sleep last night?

Claude: Based on your Oura data from last night:

Sleep score: 86 — you slept 7h 45m with 84% efficiency

Deep sleep: 76 min, REM: 82 min

HRV: 48 (average overnight)

Lowest resting HR: 45 bpm

Bedtime: 11:01 PM → 8:14 AM

Error Handling

| Scenario | Behavior | |----------|----------| | Missing OURA_TOKEN | Server exits immediately with a clear message | | Invalid/expired token (401) | Returns instructions to regenerate at cloud.ouraring.com | | Rate limited (429) | Returns a "please wait" message | | No data for date | Returns "make sure ring was worn and synced" | | Network error | Returns the underlying error message |

Errors are returned as MCP tool responses — the server never crashes on API failures.

Development

npm install
npm run build          # compile TypeScript
npm run dev            # run with hot reload (tsx)
npm start              # run compiled JS

The server logs to stderr with [oura-mcp] prefix. stdout is reserved for the MCP protocol.

Disclaimer

This is a community project and is not affiliated with or endorsed by Oura Health.

MCP Servers