oura-mcp

A Model Context Protocol server that exposes the full Oura Ring v2 API to LLM agents — including period-level sleep data, time-series HR/HRV, hypnogram rendering, SpO2, and derived analytics tools.

Why this exists

Existing community Oura MCP servers return only daily contributor scores — opaque 0–100 numbers from Oura's algorithm (deep_sleep: 11, efficiency: 88). They omit the underlying period data: actual minutes of deep/REM/light sleep, sleep stage timeline, restless periods, breathing rate, SpO2, time-series heart rate and HRV.

For any non-trivial analysis — correlation studies, intervention tracking, hypnogram visualisation, percentile comparisons — the contributor scores are useless. oura-mcp fixes that gap.

Token safety

Your Oura PAT grants full read access to your biometric history. Treat it like an API key.

• Get a token at https://cloud.ouraring.com/personal-access-tokens
• Set it via the OURA_PAT environment variable or ~/.oura-mcp/config.json — never in source code
• To revoke: cloud.ouraring.com → Personal Access Tokens → delete

If a token is accidentally committed: revoke it immediately at cloud.ouraring.com, then use git filter-repo to purge it from history (a simple delete-and-recommit leaves it in the log forever). See SECURITY.md.

Quickstart

1. Install

pip install oura-ring-mcp

Or for a developer install from source:

git clone https://github.com/jhamblin/oura-mcp.git
cd oura-mcp
pip install -e .

2. Set your PAT

# Option A — environment variable (recommended for Claude Desktop)
export OURA_PAT="your-token-here"

# Option B — config file
mkdir -p ~/.oura-mcp
echo '{"pat": "your-token-here"}' > ~/.oura-mcp/config.json

3. Register with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "oura": {
      "command": "oura-ring-mcp",
      "env": {
        "OURA_PAT": "your-token-here"
      }
    }
  }
}

Restart Claude Desktop. Ask it to call oura_personal_info to verify connectivity.

4. (Optional) Enable local cache

export OURA_MCP_CACHE_DIR=~/.oura-mcp/raw

With the cache enabled, past dates are served from disk — analyses are reproducible and don't burn API calls on repeat queries.

Tool reference

Direct API tools

Derived / analytics tools

Common parameters

All date-keyed tools accept:

• date: single day YYYY-MM-DD (defaults to today)
• start_date / end_date: inclusive range (each defaults to today)
• pat: per-call PAT override (for multi-account use)

date and start_date/end_date are mutually exclusive.

Output modes

Most data-heavy tools support a format parameter:

compact (default)

Strips bulky time-series arrays and replaces them with summaries:

• heart_rate.items (5-sec samples, 5000+/night) → heart_rate.summary = {min, max, avg, samples}
• hrv.items (~100 values/night) → hrv.summary = {min, max, avg, samples}
• sleep_phase_30_sec, movement_30_sec dropped
• sleep_phase_5_min kept (small; used for hypnogram rendering)

Typical oura_sleep response in compact mode: ~2–3 KB per night.

full

Returns the unmodified Oura API response. Use when you need raw time-series for plotting or custom analysis. Caller is responsible for context budget.

Cache behaviour

Set OURA_MCP_CACHE_DIR to enable the local cache.

• One JSON file per day: <cache_dir>/<YYYY-MM-DD>.json
• Cache-first for past dates: if the file exists, the API is not called
• Today always re-fetched: data is incomplete until ~6 hours after wake
• cache_status field on every oura_summary_table row: "hit", "miss", or "disabled"
• oura_cache_rebuild: force-refresh a date range (useful for historical backfills or after Oura revises scores retroactively)

Cache files match the structure of oura_fetch.py's raw/oura/ layout, so existing raw data from that script is compatible.

Implementation notes

Overnight sleep buffer

The Oura /sleep endpoint filters by bedtime_start, not by the logical day field. A sleep starting at 11:30 pm on Apr 12 has day = 2026-04-13 (the wake date). oura_sleep automatically expands the fetch range by ±1 day and filters results in memory by day, so overnight sleeps are never missed. This is regression-tested in tests/test_overnight_filter.py.

Pagination

Oura paginates /sleep, /heartrate, /workout, /session, and others via next_token. All tools that use these endpoints call get_all(), which follows next_token until exhausted.

Contributing

See CONTRIBUTING.md.

Security

See SECURITY.md.

License

MIT. See LICENSE.