# Oura MCP Server (`unlimiteddots/oura-mcp-server`) Actor Oura MCP Server exposes your Oura Ring API v2 data through Model Context Protocol (MCP), so AI assistants can query sleep, activity, stress, heart rate, workouts, readiness, and more. What You Get - 15+ MCP tools covering sleep, recovery, activity, vitals, and device/profile data. - **URL**: https://apify.com/unlimiteddots/oura-mcp-server.md - **Developed by:** [Unlimited Dots](https://apify.com/unlimiteddots) (community) - **Categories:** MCP servers, AI, Integrations - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing from $10.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## Oura MCP Server on Apify Oura MCP Server exposes your Oura Ring API v2 data through Model Context Protocol (MCP), so AI assistants can query sleep, activity, stress, heart rate, workouts, readiness, and more. This repository is configured to run as an Apify Actor and be consumed as an MCP server by AI tools that support MCP. ### What You Get - 17 MCP tools covering sleep, recovery, activity, vitals, and device/profile data. - Apify Actor packaging for cloud deployment. - Input schema for secure Oura token entry. - Output schema and startup status output for observability. ### Tool Coverage #### Sleep and Recovery | Tool | Description | |------|-------------| | get_sleep_data | Detailed sleep sessions with stages, HR, HRV, and breathing rate | | get_daily_sleep | Daily sleep scores and contributors | | get_sleep_time | Recommended and actual sleep timing windows | | get_daily_readiness | Readiness score with contributor breakdown | | get_daily_resilience | Recovery capacity and stress tolerance indicators | #### Activity and Fitness | Tool | Description | |------|-------------| | get_daily_activity | Steps, calories, MET levels, and activity time buckets | | get_workouts | Workout sessions with type, duration, calories, distance | | get_sessions | Guided sessions with biometrics | | get_vo2_max | VO2 max fitness estimates | #### Health Vitals | Tool | Description | |------|-------------| | get_heart_rate | Heart rate time-series data (datetime range) | | get_daily_spo2 | Daily blood oxygen saturation | | get_daily_stress | Daily stress and recovery summary | | get_daily_cardiovascular_age | Cardiovascular age estimate | #### User and Device | Tool | Description | |------|-------------| | get_personal_info | User profile data | | get_ring_configuration | Ring model, firmware, setup details | | get_rest_mode | Rest mode periods | | get_tags | User-created tags and annotations | Note: date-based tools accept optional start_date and end_date in YYYY-MM-DD. ### Run actor ### Oura Auth Token Setup This MCP server needs an Oura Personal Access Token to call the Oura API. #### 1. Create token in Oura Cloud 1. Open https://cloud.ouraring.com/personal-access-tokens 2. Sign in to your Oura account 3. Create a new personal access token 4. Copy the token value (you will use it in Apify input) #### 2. Set token in Apify Actor input (recommended) Where to set it in Apify: 1. Open your actor in Apify Console 2. Go to Input 3. Fill the field named ouraApiToken 4. Run the actor Input example: ```json { "ouraApiToken": "YOUR_OURA_PERSONAL_ACCESS_TOKEN" } ```` The actor entrypoint reads this value and maps it to OURA\_API\_TOKEN internally. #### Token troubleshooting - 401 Unauthorized usually means token is invalid, expired, or copied with extra spaces. - Confirm you are using a Personal Access Token (not another API credential type). - Regenerate the token in Oura Cloud and update the actor input if needed. ### Oura API Rate Limits Oura Cloud API applies request rate limits per token. If you hit the limit, Oura returns HTTP 429 (Too Many Requests). What this means for MCP usage: - Repeated broad date-range queries can trigger limits faster. - Some tools paginate results, which can make multiple API calls in one request. - During spikes, requests may temporarily fail until the limit window resets. Recommended practices: - Query smaller date ranges first, then expand only if needed. - Avoid firing many similar prompts in parallel. - Cache or reuse recent results in your AI workflow when possible. - On 429 errors, retry with backoff (for example 5 to 30 seconds), then try again. If your platform exposes response headers, monitor Oura rate-limit headers to track remaining quota and reset timing. In actor input, set: - ouraApiToken: your Oura personal access token At startup, the actor writes status output to: - default dataset (a startup status item) - key-value store key OUTPUT ### Connect to AI Tools Through MCP Different products expose MCP setup differently, but the pattern is the same: 1. Create and run this actor on Apify. 2. In Apify, open the actor MCP integration details. 3. Copy the MCP connection URL and any required auth token. 4. Add that MCP server in your AI tool MCP settings. #### Example MCP Config Templates Use these as templates. Product UIs and accepted keys can change, but the core values are the same: - MCP server URL from Apify - Bearer token or API key for that MCP endpoint Replace placeholders: - https://your-apify-mcp-url - YOUR\_MCP\_BEARER\_TOKEN ##### Claude ```json { "mcpServers": { "oura-apify": { "transport": "streamable-http", "url": "https://your-apify-mcp-url", "headers": { "Authorization": "Bearer YOUR_MCP_BEARER_TOKEN" } } } } ``` ##### ChatGPT ```json { "mcp_servers": [ { "name": "oura-apify", "url": "https://your-apify-mcp-url", "authorization": { "type": "bearer", "token": "YOUR_MCP_BEARER_TOKEN" } } ] } ``` ##### Gemini ```yaml mcpServers: - id: oura-apify transport: streamable-http endpoint: https://your-apify-mcp-url headers: Authorization: Bearer YOUR_MCP_BEARER_TOKEN ``` ##### Perplexity ```json { "integrations": { "mcp": [ { "label": "oura-apify", "server_url": "https://your-apify-mcp-url", "auth_header": "Authorization", "auth_value": "Bearer YOUR_MCP_BEARER_TOKEN" } ] } } ``` If your AI tool only supports UI setup, use the same values in the form fields: - Name: oura-apify - Transport: streamable-http (or HTTP MCP) - URL/Endpoint: your Apify MCP URL - Header: Authorization = Bearer YOUR\_MCP\_BEARER\_TOKEN #### Claude Use Claude's MCP server settings to add the Apify MCP endpoint, then allow tool calls from this server. Example prompts: - Analyze my last 7 days of sleep quality and explain the biggest factors. - Compare my daily stress and readiness trends for the past 14 days. - Summarize workouts this month and flag days with low recovery. #### ChatGPT In ChatGPT environments that support MCP or external tool connectors, add the Apify MCP server endpoint and authorize it. ![alt text](chatgpt.png) Example prompts: - Build a weekly recovery report from my Oura data. - Find correlations between bedtime timing and readiness score. - Give me a concise morning briefing from yesterday's Oura metrics. #### Gemini For Gemini workflows that support MCP via integrations or agent tooling, register the Apify MCP endpoint as an external tool server. Example prompts: - Identify patterns in my sleep stages over the last 30 days. - Show whether my resting heart metrics improve after rest days. - Recommend a low-intensity training week using my readiness and stress data. #### Perplexity For Perplexity environments with MCP/tool integrations, add the Apify MCP server and enable tool invocation. ![alt text](perplexity.png) Example prompts: - Pull my recent Oura data and produce a plain-language health trend summary. - Highlight unusual stress spikes and what changed around those dates. - Compare weekly activity volume and sleep efficiency. ### Example Query Patterns #### Sleep deep dive Prompt: "Use get\_sleep\_data and get\_daily\_sleep for the last 14 days. Give me trends, outliers, and three actionable changes." #### Recovery-aware training Prompt: "Use get\_daily\_readiness, get\_daily\_stress, and get\_workouts from the last 21 days. Build a simple training-intensity plan for next week." #### Stress and lifestyle notes Prompt: "Use get\_daily\_stress and get\_tags for this month. Explain which tagged behaviors seem linked to higher stress or better recovery." ### Notes - This project provides data access and summarization support, not medical diagnosis. - Oura API limits, availability, and account permissions apply. # Actor input Schema ## `ouraApiToken` (type: `string`): Personal Access Token from https://cloud.ouraring.com/personal-access-tokens ## Actor input object example ```json {} ``` # Actor output Schema ## `status` (type: `string`): Outcome of actor initialization. ## `message` (type: `string`): Human-readable details about actor run state. ## `transport` (type: `string`): MCP transport used by the server. ## `serverName` (type: `string`): MCP server display name. ## `startedAt` (type: `string`): ISO-8601 UTC timestamp when actor startup completed. ## `error` (type: `string`): Error details if startup failed. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("unlimiteddots/oura-mcp-server").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("unlimiteddots/oura-mcp-server").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call unlimiteddots/oura-mcp-server --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=unlimiteddots/oura-mcp-server", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Oura MCP Server", "description": "Oura MCP Server exposes your Oura Ring API v2 data through Model Context Protocol (MCP), so AI assistants can query sleep, activity, stress, heart rate, workouts, readiness, and more.\n\nWhat You Get - 15+ MCP tools covering sleep, recovery, activity, vitals, and device/profile data.", "version": "0.1", "x-build-id": "VxxvT23LpepimOdWU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/unlimiteddots~oura-mcp-server/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-unlimiteddots-oura-mcp-server", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/unlimiteddots~oura-mcp-server/runs": { "post": { "operationId": "runs-sync-unlimiteddots-oura-mcp-server", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/unlimiteddots~oura-mcp-server/run-sync": { "post": { "operationId": "run-sync-unlimiteddots-oura-mcp-server", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "ouraApiToken" ], "properties": { "ouraApiToken": { "title": "Oura API Token", "type": "string", "description": "Personal Access Token from https://cloud.ouraring.com/personal-access-tokens" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```