Oura MCP Server

Instructions

Implementation Reference

• src/oura_mcp_server/server.py:360-380 (handler)

  The MCP tool handler function 'get_readiness_data' that parses input date strings, checks for client initialization, and delegates to the OuraClient's get_readiness_data method.
  @mcp.tool() def get_readiness_data(start_date: str, end_date: str) -> dict[str, Any]: """ Get readiness 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 readiness 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_readiness_data(start, end) except Exception as e: return {"error": str(e)}
• src/oura_mcp_server/server.py:217-261 (helper)

  The OuraClient helper method that performs the actual API call to fetch daily readiness data from Oura API, handles the HTTP request, error checking, and data transformation by filtering out id and timestamp fields.
  def get_readiness_data( self, start_date: date, end_date: Optional[date] = None ) -> dict[str, Any]: """ Get readiness 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 readiness 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}/daily_readiness" 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 - just return the data array directly transformed_data = [] for item in raw_data.get("data", []): # Create transformed item without the id field and timestamp fields transformed_item = { k: v for k, v in item.items() if k != "id" and not k.endswith("_timestamp") and k != "timestamp" } 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)

  Utility function to parse input date strings into date objects, used by the tool handler for input validation.
  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