Google Calendar MCP Server

Instructions

Implementation Reference

• main.py:438-463 (handler)

  Handler function for the 'get_today_events' tool. Decorated with @mcp.tool() for registration. Computes today's date range and calls the helper to fetch events from Google Calendar, returning formatted JSON.

  @mcp.tool()
  def get_today_events(calendar_id: str = "primary") -> str:
      """
      Get today's events from the primary calendar
      
      Args:
          calendar_id: Calendar ID (default: primary)
      """
      try:
          # Get today's date range
          today = datetime.now()
          time_min = today.replace(hour=0, minute=0, second=0, microsecond=0).isoformat() + 'Z'
          time_max = today.replace(hour=23, minute=59, second=59, microsecond=999999).isoformat() + 'Z'
          
          result = GoogleCalendarTools.get_calendar_events(
              NANGO_CONNECTION_ID, NANGO_INTEGRATION_ID, calendar_id, time_min, time_max, 50
          )
          
          return json.dumps(result, indent=2)
      except Exception as e:
          logger.error(f"Error in get_today_events: {e}")
          return json.dumps({
              "success": False,
              "error": str(e),
              "message": "Failed to retrieve today's events"
          }, indent=2)

• main.py:139-203 (helper)

  Core helper utility (static method in GoogleCalendarTools) that implements the Google Calendar API call to list events, formats them, and handles errors. Used by get_today_events and other tools.

  @staticmethod
  def get_calendar_events(connection_id: str, provider_config_key: str, calendar_id: str = "primary", 
                         time_min: Optional[str] = None, time_max: Optional[str] = None,
                         max_results: int = 10) -> Dict:
      """Get events from Google Calendar with flexible filtering"""
      try:
          service = GoogleCalendarAuth.authenticate_google_calendar(connection_id, provider_config_key)
          
          params = {
              'calendarId': calendar_id,
              'maxResults': max_results,
              'singleEvents': True,
              'orderBy': 'startTime'
          }
          
          if time_min:
              params['timeMin'] = time_min
          if time_max:
              params['timeMax'] = time_max
          
          events_result = service.events().list(**params).execute()
          events = events_result.get('items', [])
          
          # Format events for better usability
          formatted_events = []
          for event in events:
              formatted_event = {
                  'id': event.get('id'),
                  'summary': event.get('summary', 'No Title'),
                  'description': event.get('description', ''),
                  'start': event.get('start', {}),
                  'end': event.get('end', {}),
                  'location': event.get('location', ''),
                  'status': event.get('status', ''),
                  'created': event.get('created'),
                  'updated': event.get('updated'),
                  'html_link': event.get('htmlLink'),
                  'calendar_id': calendar_id
              }
              formatted_events.append(formatted_event)
          
          return {
              "success": True,
              "events": formatted_events,
              "total_events": len(formatted_events),
              "calendar_id": calendar_id,
              "message": f"Retrieved {len(formatted_events)} events successfully"
          }
          
      except HttpError as error:
          logger.error(f'HTTP error in get_calendar_events: {error}')
          return {
              "success": False,
              "message": f"HTTP error occurred: {error}",
              "error": f"http_error_{error.resp.status if hasattr(error, 'resp') else 'unknown'}",
              "calendar_id": calendar_id
          }
      except Exception as error:
          logger.error(f'Unexpected error in get_calendar_events: {error}')
          return {
              "success": False,
              "message": f"Unexpected error occurred: {str(error)}",
              "error": "unexpected_error",
              "calendar_id": calendar_id
          }