Google Calendar MCP Server

Instructions

Implementation Reference

• main.py:465-493 (handler)

  Handler function for the 'get_upcoming_events' tool. Uses @mcp.tool() decorator for registration and schema definition via type hints and docstring. Computes date range and calls helper to fetch events.
  @mcp.tool() def get_upcoming_events(days_ahead: int = 7, calendar_id: str = "primary") -> str: """ Get upcoming events for the next N days Args: days_ahead: Number of days to look ahead (default: 7) calendar_id: Calendar ID (default: primary) """ try: # Calculate date range now = datetime.now() future = now + timedelta(days=days_ahead) time_min = now.isoformat() + 'Z' time_max = future.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_upcoming_events: {e}") return json.dumps({ "success": False, "error": str(e), "message": "Failed to retrieve upcoming events" }, indent=2)
• main.py:140-204 (helper)

  Supporting helper method in GoogleCalendarTools class that performs the actual Google Calendar API call to list events, handles authentication, formatting, and error responses.
  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 }