Oura MCP Server

Instructions

Implementation Reference

• src/oura_mcp_server/server.py:338-358 (handler)

  The MCP tool handler function for 'get_sleep_data'. It validates the Oura client, parses input date strings using parse_date, and delegates to OuraClient.get_sleep_data to fetch and return sleep data.
  def get_sleep_data(start_date: str, end_date: str) -> dict[str, Any]: """ Get sleep data for a specific date range. Args: start_date: Start date in ISO format (YYYY-MM-DD) end_date: End date in ISO format (YYYY-MM-DD) Returns: Dictionary containing sleep data """ if oura_client is None: return {"error": "Oura client not initialized. Please provide an access token."} try: start = parse_date(start_date) end = parse_date(end_date) return oura_client.get_sleep_data(start, end) except Exception as e: return {"error": str(e)}
• src/oura_mcp_server/server.py:31-122 (helper)

  The core helper method in OuraClient class that performs the actual API call to fetch sleep data, handles errors, transforms raw data by formatting durations and times, and structures the response.
  def get_sleep_data( self, start_date: date, end_date: Optional[date] = None ) -> dict[str, Any]: """ Get sleep data for a specific date range. Args: start_date: Start date for the query end_date: End date for the query (optional, defaults to start_date) Returns: Dictionary containing sleep data """ if end_date is None: end_date = start_date params = { "start_date": start_date.isoformat(), "end_date": end_date.isoformat(), } url = f"{self.BASE_URL}/sleep" response = self.client.get(url, headers=self.headers, params=params) if response.status_code != 200: error_msg = f"Error {response.status_code}: {response.text}" raise Exception(error_msg) # Get the raw response raw_data = response.json() # Transform the data transformed_data = [] for item in raw_data.get("data", []): # Format time durations awake_time = self._format_duration(item.get("awake_time", 0)) deep_sleep_duration = self._format_duration( item.get("deep_sleep_duration", 0) ) light_sleep_duration = self._format_duration( item.get("light_sleep_duration", 0) ) rem_sleep_duration = self._format_duration( item.get("rem_sleep_duration", 0) ) total_sleep_duration = self._format_duration( item.get("total_sleep_duration", 0) ) time_in_bed = self._format_duration(item.get("time_in_bed", 0)) # Format bedtime timestamps bedtime_start = self._format_time(item.get("bedtime_start", "")) bedtime_end = self._format_time(item.get("bedtime_end", "")) # Extract readiness data if available readiness = item.get("readiness", {}) readiness_score = readiness.get("score") if readiness else None readiness_contributors = ( readiness.get("contributors", {}) if readiness else {} ) # Create transformed item transformed_item = { "day": item.get("day"), "bedtime_start": bedtime_start, "bedtime_end": bedtime_end, "awake_time": awake_time, "deep_sleep_duration": deep_sleep_duration, "light_sleep_duration": light_sleep_duration, "rem_sleep_duration": rem_sleep_duration, "total_sleep_duration": total_sleep_duration, "time_in_bed": time_in_bed, "efficiency": item.get("efficiency"), "latency": item.get("latency"), "restless_periods": item.get("restless_periods"), "average_breath": item.get("average_breath"), "average_heart_rate": item.get("average_heart_rate"), "average_hrv": item.get("average_hrv"), "lowest_heart_rate": item.get("lowest_heart_rate"), } # Add readiness data if available if readiness_score is not None: transformed_item["readiness_score"] = readiness_score transformed_item["readiness_contributors"] = readiness_contributors transformed_data.append(transformed_item) # Return with the original structure but with transformed data return {"data": transformed_data}
• src/oura_mcp_server/server.py:310-326 (helper)

  Helper function used by the tool handler to parse input date strings into date objects.
  def parse_date(date_str: str) -> date: """ Parse a date string in ISO format (YYYY-MM-DD). Args: date_str: Date string in ISO format Returns: Date object """ try: return date.fromisoformat(date_str) except ValueError as err: raise ValueError( f"Invalid date format: {date_str}. Expected format: YYYY-MM-DD" ) from err
• src/oura_mcp_server/server.py:338-338 (registration)

  The @mcp.tool() decorator registers the get_sleep_data function as an MCP tool.
  def get_sleep_data(start_date: str, end_date: str) -> dict[str, Any]: