Skip to main content
Glama

oura-mcp

CI npm License: MIT

A Model Context Protocol server for the Oura Ring API v2. Exposes sleep, activity, readiness, heart rate, and workout data to MCP-compatible clients (Claude Desktop, Claude Code, Cursor, ...) via OAuth.

Quick start

npx @yasuakiomokawa/oura-mcp configure

The wizard collects your Oura Client ID/Secret, walks through browser OAuth, saves tokens to ~/.config/oura-mcp/, and adds an mcpServers.oura entry to any detected MCP client config. Restart the client and the tools below are available.

Re-running configure pre-fills the saved Client ID / port so you only need to press Enter to keep them. Type --force to wipe saved state and start from scratch:

npx @yasuakiomokawa/oura-mcp configure --force

Related MCP server: oura-ring-mcp-server

Prerequisites

  1. Register an Oura developer app at https://cloud.ouraring.com/oauth/applications

  2. Redirect URI must be exactly: http://localhost:54321/callback (or http://localhost:<port>/callback if you customize OURA_CALLBACK_PORT)

  3. Enable the read scopes you need (Email, Personal info, Daily activity, Heart rate, Workout, Tag, Session, SpO2, Ring configuration, Stress, Heart health)

  4. Note the Client ID and Client Secret — you'll enter them in npx @yasuakiomokawa/oura-mcp configure

Installation

Three paths depending on your client:

1. MCP Registry (auto-discovery clients)

Once published to the official MCP Registry, supported clients can install io.github.YasuakiOmokawa/oura-mcp from their UI. The wizard step still has to run once to obtain OAuth tokens.

2. Manual config (Claude Desktop / Claude Code / Cursor)

Run npx @yasuakiomokawa/oura-mcp configure — Step 4 of the wizard auto-detects:

  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows)

  • Claude Code (user): ~/.claude.json

  • Claude Code (project): ./.mcp.json

  • Cursor (user): ~/.cursor/mcp.json

  • Cursor (project): ./.cursor/mcp.json

Each detected file is backed up to <file>.bak.<ISO-timestamp> before an atomic write.

To configure manually, add to your client config:

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "@yasuakiomokawa/oura-mcp"]
    }
  }
}

3. Skill (optional)

The companion oura-api-skill ships per-endpoint reference and three workflow recipes (weekly review / sleep trend / recovery check). Bundle it as a Claude Code plugin or import into your skills directory.

Tools provided

Tool

Purpose

oura_authenticate

Start OAuth flow in browser; returns the URL. Used after refresh_token expires.

oura_auth_status

Check current token validity and expiry.

oura_clear_auth

Wipe stored tokens.

oura_api_list_paths

List every supported GET endpoint with summaries.

oura_api_get

Generic GET to /v2/.... Auto-paginates via max_pages (1-20) or accepts next_token in params.

oura_api_get returns structuredContent with { status, data, next_token, pages_fetched, has_more }.

Configuration

Two ways. The config file (Option A) is the recommended path — it stores secrets at-rest with 0600 and is self-healing. Environment variables (Option B) are kept for CI / Docker / ephemeral environments where writing a file is impractical, but they leak more easily and are not recommended for daily use.

Run the wizard once and forget about it:

npx @yasuakiomokawa/oura-mcp configure

This writes:

~/.config/oura-mcp/config.json   # 0600, contains clientId / clientSecret / callbackPort
~/.config/oura-mcp/tokens.json   # 0600, contains the OAuth access / refresh tokens

Permissions are re-checked on every load and chmod'd back to 0600 if anything else touched them.

config.json schema:

{
  "schemaVersion": 1,
  "clientId": "...",
  "clientSecret": "...",
  "callbackPort": 54321
}

Option B — environment variables (CI / Docker only)

OURA_CLIENT_ID=...
OURA_CLIENT_SECRET=...        # must be set together with OURA_CLIENT_ID
OURA_CALLBACK_PORT=54321      # optional; safe to set in env regardless of Option A/B

When the server boots and both OURA_CLIENT_ID and OURA_CLIENT_SECRET are set, it uses them and emits a config.env_credentials warning to stderr.

Why not recommended:

  • process.env is readable from /proc/<pid>/environ by any process running as the same user.

  • Environment is inherited by every child process the server spawns.

  • Crash dumps and observability tools that capture process.env will leak the secret.

  • OURA_CLIENT_SECRET=... npx ... typed at the shell ends up in shell history.

OURA_CALLBACK_PORT is not a secret and is fine to pass via env in either mode.

Never use args for secrets

Process arguments are visible to other users via ps / /proc/<pid>/cmdline. Use the env block of your MCP client config:

{
  "mcpServers": {
    "oura": {
      "command": "npx",
      "args": ["-y", "@yasuakiomokawa/oura-mcp"],
      "env": { "OURA_CLIENT_ID": "...", "OURA_CLIENT_SECRET": "..." }
    }
  }
}

Troubleshooting

  • "refresh_token expired" — run oura_authenticate (in chat) or npx @yasuakiomokawa/oura-mcp configure (in terminal).

  • Port 54321 already in use — set OURA_CALLBACK_PORT=<other port> and update the redirect URI in your Oura developer app to match.

  • "Path not found" — verify the path with oura_api_list_paths. Common slips: missing /v2/ prefix, typo in daily_sleep.

  • Setup hangs at "Waiting for authorization" — you haven't approved in the browser yet, or the authorize page was opened in a different browser session than the one with localhost reachability.

  • No log output — set OURA_LOG_LEVEL=debug for verbose stderr logging.

Development

git clone https://github.com/YasuakiOmokawa/oura-mcp.git
cd oura-mcp
npm install
npm test
npm run build

Useful scripts:

  • npm run lint / npm run typecheck — Biome + TypeScript checks

  • npm run test:coverage — Vitest with V8 coverage

  • npm run update:docs — re-fetch the Oura OpenAPI schema and regenerate skills/oura-api-skill/references/

License

MIT

Available Tools

5 tools
oura_api_getOura API GETA
Read-onlyIdempotent

Generic GET to Oura Ring API v2. Use oura_api_list_paths to see endpoints. Pagination via max_pages or pass next_token in params.

Inputs: path (required), params, max_pages. Returns: data, status, has_more, next_token, +1 more

oura_api_list_pathsList Oura API endpointsA
Read-onlyIdempotent

List all available Oura API v2 GET endpoints with summaries.

Inputs: no named parameters.

oura_authenticateAuthenticate with OuraA

Start OAuth authorization flow. Returns a URL to open in browser. Used for re-authentication after refresh_token expires.

Inputs: no named parameters.

oura_auth_statusAuthentication statusA
Read-onlyIdempotent

Check current authentication state and token expiry.

Inputs: no named parameters.

oura_clear_authClear authenticationA
DestructiveIdempotent

Delete stored tokens. Re-authenticate via oura_authenticate after this.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a distinct purpose: listing endpoints, generic GET requests, initiating OAuth, checking auth status, and clearing tokens. No overlap or ambiguity in their roles.

    Naming Consistency4/5

    All tools share the 'oura_' prefix, and most follow a verb_noun pattern (e.g., oura_authenticate, oura_auth_status). Minor inconsistency with 'oura_api_get' and 'oura_api_list_paths' mixing 'api' with the verb, but overall pattern is maintained.

    Tool Count5/5

    With only 5 tools, the server is well-scoped for its purpose: authentication management and a generic GET endpoint. No unnecessary tools.

    Completeness3/5

    The server covers authentication and read operations via a generic GET, but lacks write operations (POST/PUT/DELETE) or any specialized endpoints. This may be sufficient for some use cases but leaves gaps for a full API surface.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server for the Withings Health API with per-user OAuth2, enabling users to securely access their own health data (measures, activity, sleep, workouts, heart rate, devices, and goals) and optionally add measurements.
      12
      Apache 2.0
    • A
      license
      A
      quality
      B
      maintenance
      Exposes the Oura API v2 as an MCP server with tools to query all 19 data collections (e.g., sleep, heartrate) with automatic pagination and explicit truncation warnings.
      6
      95 PyPI
      MIT