oura-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@oura-mcp what was my sleep score last night?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 configureThe 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 --forceRelated MCP server: oura-ring-mcp-server
Prerequisites
Register an Oura developer app at https://cloud.ouraring.com/oauth/applications
Redirect URI must be exactly:
http://localhost:54321/callback(orhttp://localhost:<port>/callbackif you customizeOURA_CALLBACK_PORT)Enable the read scopes you need (Email, Personal info, Daily activity, Heart rate, Workout, Tag, Session, SpO2, Ring configuration, Stress, Heart health)
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.jsonClaude Code (project):
./.mcp.jsonCursor (user):
~/.cursor/mcp.jsonCursor (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 |
| Start OAuth flow in browser; returns the URL. Used after |
| Check current token validity and expiry. |
| Wipe stored tokens. |
| List every supported |
| Generic |
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.
Option A — config file (recommended)
Run the wizard once and forget about it:
npx @yasuakiomokawa/oura-mcp configureThis writes:
~/.config/oura-mcp/config.json # 0600, contains clientId / clientSecret / callbackPort
~/.config/oura-mcp/tokens.json # 0600, contains the OAuth access / refresh tokensPermissions 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/BWhen 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.envis readable from/proc/<pid>/environby 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.envwill 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) ornpx @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 indaily_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=debugfor verbose stderr logging.
Development
git clone https://github.com/YasuakiOmokawa/oura-mcp.git
cd oura-mcp
npm install
npm test
npm run buildUseful scripts:
npm run lint/npm run typecheck— Biome + TypeScript checksnpm run test:coverage— Vitest with V8 coveragenpm run update:docs— re-fetch the Oura OpenAPI schema and regenerateskills/oura-api-skill/references/
License
Available Tools
5 toolsoura_api_getOura API GETARead-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 endpointsARead-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 statusARead-onlyIdempotent
Check current authentication state and token expiry.
Inputs: no named parameters.
oura_clear_authClear authenticationADestructiveIdempotent
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
Scored across 5 tools
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.
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.
With only 5 tools, the server is well-scoped for its purpose: authentication management and a generic GET endpoint. No unnecessary tools.
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
Related MCP Connectors
Multi-tenant hosted MCP server for Oura Ring — 21 read-only tools, OAuth per user.
MCP server for Withings health data — sleep, activity, heart, and body metrics.
Remote MCP server for training, nutrition, wellness, and performance data with OAuth 2.0.
Hosted MCP server with managed OAuth for 15+ toolkits: Google Workspace, Fitbit, Oura, Kalshi, etc.
Related MCP Servers
- AlicenseAqualityDmaintenanceComprehensive MCP server for the Oura Ring API v2, exposing 17 tools to access sleep, activity, heart rate, stress, SpO2, workouts, and user data.171MIT
- AlicenseAqualityCmaintenanceMCP server for the Oura Ring API v2, enabling natural language queries about sleep, readiness, activity, heart rate, and more.2952 npm1MIT
- AlicenseAqualityCmaintenanceMCP 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.12Apache 2.0
- AlicenseAqualityBmaintenanceExposes 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.695 PyPIMIT