get_calendar_events
Retrieve Google Calendar events within specified time ranges using calendar ID and filters to view schedules and manage appointments.
Instructions
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)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| calendar_id | No | primary | |
| time_min | No | ||
| time_max | No | ||
| max_results | No |
Implementation Reference
- main.py:338-367 (handler)The primary MCP tool handler function for 'get_calendar_events', decorated with @mcp.tool() for automatic registration. It handles input parameters, calls the underlying helper, and returns JSON-formatted results.@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)Supporting utility in GoogleCalendarTools class that performs the actual Google Calendar API call to fetch and format events. Called by the main handler.@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:338-338 (registration)The @mcp.tool() decorator registers the get_calendar_events function as an MCP tool.@mcp.tool()