Oura MCP Server

Instructions

Get sleep data for today.

Returns:
    Dictionary containing sleep data for today

Implementation Reference

• src/oura_mcp_server/server.py:407-422 (handler)

  The handler function decorated with @mcp.tool(), which registers and implements the 'get_today_sleep_data' tool. It fetches today's sleep data using the OuraClient.

  @mcp.tool()
  def get_today_sleep_data() -> dict[str, Any]:
      """
      Get sleep data for today.
  
      Returns:
          Dictionary containing sleep data for today
      """
      if oura_client is None:
          return {"error": "Oura client not initialized. Please provide an access token."}
  
      try:
          today = date.today()
          return oura_client.get_sleep_data(today, today)
      except Exception as e:
          return {"error": str(e)}

• src/oura_mcp_server/server.py:31-121 (helper)

  The OuraClient method that performs the actual API call and data transformation for sleep data, called by the tool handler.

  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 to parse date strings, used in other tools but available for date handling.

  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