oura-mcp

A read-only MCP server for the Oura API v2, giving agents access to Oura Ring health data: sleep, activity, readiness, stress, SpO2, heart rate, workouts, VO2 max, and more.

Webhooks are intentionally not implemented — this server is meant for sparing, on-demand use by a personal-assistant agent, not for change tracking.

Tools

Tool	Purpose
get_personal_info	Age, weight, height, biological sex, email
list_documents	Any dated collection: sleep, daily_activity, daily_readiness, daily_sleep, daily_spo2, daily_stress, daily_resilience, daily_cardiovascular_age, enhanced_tag, rest_mode_period, session, sleep_time, vO2_max, workout
get_document	A single document by id
list_time_series	High-resolution heartrate or ring_battery_level samples (supports latest)
get_ring_configuration	Ring hardware, size, color, firmware

Configuration

All configuration is via environment variables, so a bearer token can be injected by an MCP auth proxy:

Variable	Meaning
OURA_ACCESS_TOKEN	Bearer token — an Oura personal access token or OAuth2 access token. Read per-request, never logged.
OURA_BASE_URL	API base URL. Default https://api.ouraring.com.
OURA_SANDBOX	Set to 1 to use Oura's auth-free sandbox endpoints (fake data), for testing without a token.

Running

uv run oura-mcp                 # stdio transport (default)
uv run oura-mcp --transport http --host 127.0.0.1 --port 8000

Example client config (stdio):

{
  "mcpServers": {
    "oura": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/oura-mcp", "oura-mcp"],
      "env": { "OURA_ACCESS_TOKEN": "..." }
    }
  }
}

Development

uv run pytest
uv run ruff check .

Notes

• Daily summaries and sleep sessions are attributed to the calendar day they end on: last night's sleep is on today's date.
• List responses are paginated; pass the returned next_token back to get the next page.
• The Oura API rate limit is 5000 requests per 5 minutes — not a concern for interactive agent use.
• Sandbox limitations (Oura-side, verified against the live API): personal_info is not available (404), single-document lookups return 500, and the fields filter is ignored.