ouracli
Agent-first · Oura Ring API v2

Your Oura data, in the hands of your agent.

A fast, agent-first CLI and MCP server for the Oura Ring. Give Claude or Codex read access to your own sleep, readiness, HRV and workouts — and let it help you make sense of your health.

Add it to Claude or Codex Try with zero credentials
$ brew tap ouracli/oura && brew install oura

macOS & Linux via Homebrew · or go install github.com/ouracli/oura/cmd/oura@latest

The point of the whole thing

Point your agent at your own ring.

ouracli doubles as an MCP server — every Oura endpoint becomes a tool your agent can call. One command wires it up. Your tokens stay in your OS keychain, never in the model's context.

1

Install the CLI (Homebrew, above) and register it as an MCP server in Claude Code:

$ claude mcp add oura -- oura mcp serve
2

No ring yet? Explore the real API shape with fake data and zero credentials:

$ claude mcp add oura-sandbox -- oura mcp serve --sandbox
3

Connect your real ring once with oura auth login, then just ask: “How has my HRV trended against my readiness this week?”

1

Install the CLI (Homebrew, above), then add it to the Codex CLI:

$ codex mcp add oura -- oura mcp serve
2

Prefer editing config? Add this block to ~/.codex/config.toml:

[mcp_servers.oura]
command = "oura"
args = ["mcp", "serve"]
3

Connect your real ring once with oura auth login — or append --sandbox above to try it credential-free first.

Built for agents, honest with humans

Every endpoint. Clean JSON. Nothing hidden.

🧩

The full API, current

Every Oura API v2 data type — including the newest: resilience, cardiovascular age, VO2 max, SpO2, stress. Nothing left on the table.

🤖

Self-describing

oura schema emits a live tool manifest — flags, types, exit codes. Your agent loads it once instead of scraping help text.

📐

JSON on stdout, always

One document, an NDJSON stream, or a typed error envelope — never prose. Branch on .error.kind, not grep.

🔐

Secrets stay secret

Tokens live in your OS keychain (or an AES-256-GCM encrypted file), resolved per request. They never touch the agent's context.

🧪

Zero-credential sandbox

Oura's public sandbox mirrors every endpoint with fake data. See the real JSON shape before wiring up a single credential.

⚡

One binary, two tools

The same registry drives the CLI, the schema manifest, and the MCP server — so they can never drift apart. One go binary, no runtime.

Why I built this

The tools existed. They just didn't work.

Every Oura CLI and MCP I tried came up short — stale on the API, missing the newest and most interesting data types, or simply broken when I reached for them.

The Oura API had already shipped resilience, cardiovascular age, VO2 max, richer sleep and stress data. None of it was exposed. So I built the tool I wanted: one that keeps pace with the full API, is designed from the ground up for an agent to drive, and treats your credentials with the care they deserve.

Complete, and kept current

Coverage of the whole v2 surface — not just sleep and activity, but every endpoint Oura ships.

Empowering, not extractive

This is your data. The goal is to put it in your hands — and your agent's — so it can actually help your health journey.

Agentic by design

Typed errors, a stable exit-code enum, a schema manifest, and an MCP server — built so a model can drive it reliably.

The command tour

One verb per data type.

Every command defaults to the last 7 days and speaks the same flags. Run oura schema for the full, live list.

oura sleepDaily sleep score + contributors
oura readinessReadiness score + HRV balance
oura activitySteps, calories, MET minutes
oura heartrateTime-series bpm by source
oura sleep-periodsPer-period phases, HRV, breathing
oura resilienceLong-term resilience level
oura stressHigh-stress & recovery time
oura spo2Blood-oxygen % during sleep
oura cardio-ageEstimated vascular age
oura vo2maxCardiorespiratory fitness
oura workoutsLogged workouts & intensity
oura sessionsMeditation & breathing sessions
oura sleep-timeRecommended bedtime window
oura tagsUser-annotated events
oura rest-modeRest Mode periods
oura profileAge, sex, height, weight

Plus oura auth, oura doctor, oura schema, and oura mcp serve. Every data command supports --all (NDJSON pagination), --fields, --start/--end, and --pretty.

60-second start

See it work before you commit a single credential.

Real API shapes, fake data, no account. Then connect your ring whenever you're ready.

$ oura sleep --sandbox --pretty
Read the docs on GitHub ↗