Mcpforoura MCP Server

mcpforoura

Ask your AI assistant about your Oura Ring data in plain language. mcpforoura is a hosted, multi-tenant Model Context Protocol server for Oura Ring, live at https://mcp-oura.smirnov.link/mcp. Connect it to Claude (or any MCP-compatible client), authorize once with Oura, and query your sleep, readiness, activity, biometrics, and long-term trends across 21 read-only tools. Multi-tenant OAuth: each user authenticates to their own Oura account. Read-only. Built on Cloudflare Workers.

Listed on Smithery and the official MCP Registry.

Small-scale connector — currently in Oura's development-mode 10-user cap; production application is pending. Not affiliated with Oura Health Oy.

Status: deployed and serving. 21 tools live — core sleep/readiness/activity data plus biometrics, composite snapshots, and analytics. Phase 5 cycle tools removed pending Oura API support (see "Not available" below). Full build history is in the milestone table.

What you can ask

Once connected, your assistant can answer questions like:

• "How did I sleep last night?" — stages, timing, HR and HRV
• "Is my HRV normal for me this week?" — compared against your personal baseline
• "How am I today?" — a morning briefing of readiness, recommended sleep, and yesterday's stats
• "Does alcohol hurt my recovery?" — correlate a logged tag against any metric
• "Flag any days this month that were unusual for me." — statistical anomaly detection

Those map onto 21 tools across 4 phases (Phase 5 cycle tools removed — see "Not available" below):

Core (M6 originals)

Phase 1 — Activity & tagging

Phase 2 — Tier A daily metrics

Phase 3 — Composite tools

Phase 4 — Analytics

Not available

Cycle analytics (get_cycle_phase, get_cycle_history, compare_metric_across_cycle_phases) were initially planned for Phase 5 but Oura's public v2 API does not expose menstrual cycle endpoints — the Cycle Insights feature lives in the Oura app only. The tools were removed after a beta user hit 404s; see git history (feat/phase-5-cycle and feat/remove-cycle-tools branches) for the reasoning trail. Tag-based logging via get_tags can serve as a partial workaround if users tag period start days manually.

Adding the connector in Claude

1. Click Add to Claude. It opens the Add custom connector dialog on claude.ai with the name (Oura) and URL filled in. Check both values, then click Add.
2. Approve on this server's consent page → redirected to Oura → consent there → returned to Claude.

To add it by hand, go to Customize → Connectors → Add custom connector and enter https://mcp-oura.smirnov.link/mcp as the URL.

On a Team or Enterprise plan, an Owner adds custom connectors for the whole organization. Owners can use the organization version of the link. Members then connect from Customize → Connectors with their own Oura account.

The connector currently caps at 10 authorized users (Oura's default development-mode limit). To lift the cap, the Oura developer application must be approved for production by Oura.

Architecture

Two-stage OAuth on Cloudflare Workers:

• Flow A (MCP client ↔ this server). Handled by @cloudflare/workers-oauth-provider. Standard OAuth2 + PKCE + dynamic client registration. Consent page is rendered server-side and includes a CSRF token.
• Flow B (this server ↔ Oura). Hand-rolled. Triggered inside Flow A: redirect to cloud.ouraring.com, exchange the returned code for tokens, fetch /personal_info to derive a stable user id, store the token AES-GCM encrypted in Cloudflare KV, then complete Flow A with that user id attached as props.

The /mcp endpoint is stateless: for each request, createMcpHandler from Cloudflare's agents SDK builds an MCP server for the signed-in user, and that server routes the call to a typed tool handler. Each tool builds an OuraClient per call that handles token refresh, 401 disambiguation (re-auth vs. endpoint gated vs. account membership inactive), and 429 exponential backoff.

See CLAUDE.md for the full file-by-file walkthrough.

Setup (operator)

One-time:

1. Oura developer app — cloud.ouraring.com → API Applications → New.

   • Redirect URI: https://<your-host>/oura/callback
   • Privacy Policy URL: https://<your-host>/privacy
   • Terms of Service URL: https://<your-host>/tos

2. Cloudflare KV namespaces (paste IDs into wrangler.jsonc):

   npx wrangler kv namespace create mcpforoura-OAUTH_KV
   npx wrangler kv namespace create OURA_TOKENS
   npx wrangler kv namespace create OURA_CACHE
   

   The mcpforoura- prefix on OAUTH_KV avoids colliding with other workers in the same CF account that also use a binding called OAUTH_KV.

3. First deploy (registers the worker so secrets can attach to it):

   npx wrangler deploy
   

4. Secrets:

   echo -n "$CLIENT_ID"     | npx wrangler secret put OURA_CLIENT_ID
   echo -n "$CLIENT_SECRET" | npx wrangler secret put OURA_CLIENT_SECRET
   openssl rand -base64 32  | tr -d '\n' | npx wrangler secret put ENCRYPTION_SECRET
   

   Keep a copy of ENCRYPTION_SECRET somewhere safe — if it's lost, stored tokens cannot be decrypted and all users have to re-authorize.

5. Custom domain — if the apex zone is in the same Cloudflare account, the routes block in wrangler.jsonc (with custom_domain: true) attaches the subdomain automatically on next deploy. Otherwise, configure it manually in the Cloudflare dashboard.

Discoverability

The server publishes the following metadata for MCP registry aggregators:

Submitting the server to the official MCP Registry (which PulseMCP, mcp.so, and other aggregators consume from):

# One-time, from this repo root
go install github.com/modelcontextprotocol/registry/cmd/mcp-publisher@latest
mcp-publisher login dns smirnov.link   # prints a TXT record to add in Cloudflare DNS
mcp-publisher publish                  # uses server.json in the repo root

Submitting to Smithery: paste https://mcp-oura.smirnov.link/mcp at smithery.ai/new and walk through OAuth during their scan.

Submitting to Glama: use "Add Server" on glama.ai/mcp/servers (they pick up maintainer info from /.well-known/glama.json automatically).

Development

cp .dev.vars.example .dev.vars      # fill in
npm install
npm run dev

Local development hits the same Oura redirect URI as production, so it's usually easier to test via wrangler dev --remote so the consent flow completes against deployed infrastructure.

Privacy & data handling

• Oura OAuth tokens are encrypted at rest (AES-GCM, per-user HKDF-derived key) in Cloudflare Workers KV.
• Oura ring data is fetched on demand and (when the cache layer ships) may be briefly cached in KV with TTLs ranging from 5 minutes (today's data) to 24 hours (historical).
• Ring data is not logged.
• Disconnecting the connector revokes the OAuth grant; tokens become unreachable.
• See /privacy on the deployed site for the full policy.

Status

Deployed at https://mcp-oura.smirnov.link on the Smirnov Labs Cloudflare account. Custom domain mapped via the routes block in wrangler.jsonc. Three KV namespaces provisioned (mcpforoura-OAUTH_KV, OURA_TOKENS, OURA_CACHE). Three secrets set (OURA_CLIENT_ID, OURA_CLIENT_SECRET, ENCRYPTION_SECRET).

Build progress

License

MIT. See LICENSE.