Oura Ring MCP server

oura-mcp

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

Prerequisites

(or http://localhost:/callback if you customize OURACALLBACKPORT)

1. Register an Oura developer app at https://cloud.ouraring.com/oauth/applications
2. Redirect URI must be exactly: http://localhost:54321/callback

1. Enable the read scopes you need (Email, Personal info, Daily activity, Heart rate, Workout, Tag, Session, SpO2, Ring configuration, Stress, Heart health)
2. 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/claudedesktopconfig.json (macOS) or %APPDATA%\Claude\claudedesktopconfig.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 .bak. 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

ouraapiget returns structuredContent with { status, data, nexttoken, pagesfetched, 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.

Option A — config file (recommended)

Run the wizard once and forget about it:

Shortened. The full README is on GitHub.