Oura Ring Model Controller Protocol Server

What is Oura Ring Model Controller Protocol Server about?

Enables AI assistants to retrieve and interpret a user’s Oura Ring data—sleep, activity, readiness, heart rate, and more—through a structured MCP interface.

How to use Oura Ring Model Controller Protocol Server?

1. Prerequisites: Install Node.js v18+ and obtain an Oura Personal Access Token.
2. Clone & install:

   git clone https://github.com/rajvirtual/oura-mcp-server.git
   cd oura-mcp-server
   npm install
   

3. Configure: Create a .env file in the project root:

   OURA_TOKEN=your_personal_access_token_here
   

4. Build:

   npm run build
   

5. Start the server (preferred npx command):

   npx -y oura-mcp-server
   

   The server will listen for MCP requests from compatible AI assistants.

Key Features

• Secure Oura API integration with token‑based authentication.
• Pre‑defined health‑analysis prompts for common queries.
• Customizable query syntax for detailed metric extraction.
• Automatic conversion of duration fields to human‑readable units.
• Built‑in calculations for sleep efficiency, percentages, and correlations.
• Visualization support: AI can request charts/graphs that the server renders.

Use Cases

• Ask an AI assistant to summarize weekly sleep quality and highlight anomalies.
• Analyze the impact of specific meals on readiness scores.
• Compare stress levels on workdays vs. weekends.
• Generate a chart showing HRV trends alongside sleep stages.
• Create visual reports for personal health reviews or sharing with clinicians.

FAQ

Q: Which Oura data can be accessed? A: All metrics provided by the Oura API, including sleep, activity, readiness, heart rate, HRV, and custom tags.

Q: Do I need to run the server continuously? A: Yes, the server must be running to respond to MCP calls from the AI assistant.

Q: How are visualizations delivered? A: The AI includes a “visualize” request; the server generates image files (PNG/GIF) and returns URLs or embeds them in the response.

Q: Is the token stored securely? A: The token is read from the .env file at runtime and never hard‑coded in source code.

Q: Can I extend the prompt library? A: Absolutely—add new prompt templates in the server’s configuration to tailor analyses to personal needs.

Oura Ring Model Controller Protocol (MCP) Server

This server enables AI assistants to access and analyze your Oura Ring data through the Model Controller Protocol (MCP). It provides a structured way to fetch and understand your health metrics.

Features

• Secure access to your Oura Ring data
• Pre-defined prompts for common health analysis tasks
• Customizable queries for specific health insights
• Support for analyzing correlations between different metrics
• Proper handling of time units and calculation guidelines
• Visualization capabilities for health metrics

Getting Started

Prerequisites

• Node.js v18 or higher
• An Oura Ring account with Personal Access Token

Installation

1. Clone the repository:

   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 root directory with your Oura API token:

   OURA_TOKEN=your_personal_access_token_here
   

4. Build the project:

   npm run build
   

5. Start the server:

   npm start
   

Getting an Oura Personal Access Token

1. Go to the Oura Developer website
2. Log in with your Oura account
3. Create a new Personal Access Token
4. Copy the token to your .env file

Example Prompts

You can ask Claude things like:

• "Show me my sleep data for the last week and explain what it means"
• "Analyze how my meals affect my readiness scores"
• "Compare my stress levels on workdays versus weekends"
• "Show me my heart rate during sleep for nights when I had alcohol"
• "Visualize my sleep efficiency trends for the past month" (Claude will generate charts!)
• "Create a visualization comparing my readiness scores after different meals"

Data Visualization

Claude can create visual charts to help you understand your health data. Simply ask Claude to "visualize" or "create a chart" of specific metrics. For example:

• "Visualize my sleep stages over the past week"
• "Create a chart showing the correlation between HRV and sleep quality"
• "Make a bar graph comparing my activity scores by day of week"
• "Plot my resting heart rate against stress levels"

Data Handling Guidelines

This server follows these key guidelines:

• All duration fields are in seconds and converted to hours/minutes for display
• Sleep percentages are calculated using total_sleep_duration as denominator
• Sleep efficiency is calculated as (total_sleep_duration / time_in_bed * 100)
• Custom tags contain meal information in the comment field

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.