Google Calendar MCP Server

Instructions

Implementation Reference

• main.py:338-367 (handler)

  MCP tool handler for 'get_calendar_events'. Registers the tool and handles input parameters, delegates to GoogleCalendarTools.get_calendar_events, serializes result to JSON.

  @mcp.tool()
  def get_calendar_events(
      calendar_id: str = "primary",
      time_min: Optional[str] = None,
      time_max: Optional[str] = None,
      max_results: int = 10
  ) -> str:
      """
      Get events from a specific Google Calendar
      
      Args:
          calendar_id: Calendar ID (default: primary)
          time_min: Lower bound for event start time (ISO format)
          time_max: Upper bound for event start time (ISO format)
          max_results: Maximum number of events to return (default: 10)
      """
      try:
          result = GoogleCalendarTools.get_calendar_events(
              NANGO_CONNECTION_ID, NANGO_INTEGRATION_ID, calendar_id, time_min, time_max, max_results
          )
          
          return json.dumps(result, indent=2)
      except Exception as e:
          logger.error(f"Error in get_calendar_events: {e}")
          return json.dumps({
              "success": False,
              "error": str(e),
              "message": "Failed to retrieve calendar events"
          }, indent=2)

• main.py:139-203 (helper)

  Core helper function in GoogleCalendarTools class that implements the actual Google Calendar API logic for fetching, formatting events, and error handling.

  @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
          }

• main.py:339-353 (schema)

  Input schema defined by function parameters and docstring in the MCP tool handler.

  def get_calendar_events(
      calendar_id: str = "primary",
      time_min: Optional[str] = None,
      time_max: Optional[str] = None,
      max_results: int = 10
  ) -> str:
      """
      Get events from a specific Google Calendar
      
      Args:
          calendar_id: Calendar ID (default: primary)
          time_min: Lower bound for event start time (ISO format)
          time_max: Upper bound for event start time (ISO format)
          max_results: Maximum number of events to return (default: 10)
      """

• main.py:338-338 (registration)

  Registration of the 'get_calendar_events' tool using FastMCP @mcp.tool() decorator.

  @mcp.tool()