oura

This MCP server provides controlled access to your Oura Ring data through the Model Controller Protocol (MCP). It exposes pre-defined prompts and flexible query capabilities so AI assistants can fetch, analyze, and visualize your health metrics (sleep, readiness, activity, HRV, etc.) in a structured way. Use the built-in prompts to request common analyses like sleep patterns, readiness trends, or correlations between meals and sleep quality, and leverage the visualization features to generate charts automatically. To start using it, ensure your Oura Personal Access Token is available in a .env file and that the server is running; then you can issue MCP-compatible requests to retrieve data, run analyses, and request visualizations.

Examples of capabilities include: requesting sleep data for a date range and receiving an explanation of the results; analyzing correlations between activity scores and sleep efficiency; generating visualizations such as sleep stages over time or HRV versus sleep quality charts; and comparing stress or readiness metrics across days of the week. The server handles time units and calculation guidelines to present results in human-friendly terms, including converting durations to hours/minutes and normalizing percentages where needed.

Prerequisites:

• Node.js v18 or higher
• npm (comes with Node.js)
• An Oura Ring account with a Personal Access Token

Installation steps:

1. Clone the repository and navigate into it: git clone https://github.com/yourusername/oura-mcp-server.git cd oura-mcp-server

2. Install dependencies: npm install

3. Create a .env file in the project root and add your Oura API token: OURA_TOKEN=your_personal_access_token_here

4. Build the project (if the project uses a build step): npm run build

5. Start the server: npm start

Notes:

• If your setup uses a dist/server.js after building, the MCP config should point to that path (see mcp_config above).
• Ensure the environment variable OURA_TOKEN is kept secret and is not committed to version control.

Tips and caveats:

• Keep your Oura token secure; treat it as a sensitive credential.
• If you encounter token scoping issues, verify the token has the necessary read permissions for sleep, activity, and hydration data.
• The MCP server may implement rate limits according to the Oura API; if you see throttling, consider spacing requests or caching results where appropriate.
• Time units are standardized by the server (durations in seconds converted to hours/minutes for display).
• For best results with visualizations, request specific charts like 'Visualize sleep stages over the past week' or 'Plot HRV vs sleep quality' to trigger chart generation.
• If you upgrade Node.js, re-install dependencies to avoid version mismatches.