Google Workspace MCP Server

Instructions

Implementation Reference

• gcalendar/calendar_tools.py:356-526 (handler)

  The main handler function that executes the create_event tool logic. It constructs the event body from parameters, handles special features like attachments, Google Meet conference, custom reminders, and inserts the event into the specified Google Calendar using the Google API.
  async def create_event( service, user_google_email: str, summary: str, start_time: str, end_time: str, calendar_id: str = "primary", description: Optional[str] = None, location: Optional[str] = None, attendees: Optional[List[str]] = None, timezone: Optional[str] = None, attachments: Optional[List[str]] = None, add_google_meet: bool = False, reminders: Optional[Union[str, List[Dict[str, Any]]]] = None, use_default_reminders: bool = True, ) -> str: """ Creates a new event. Args: user_google_email (str): The user's Google email address. Required. summary (str): Event title. start_time (str): Start time (RFC3339, e.g., "2023-10-27T10:00:00-07:00" or "2023-10-27" for all-day). end_time (str): End time (RFC3339, e.g., "2023-10-27T11:00:00-07:00" or "2023-10-28" for all-day). calendar_id (str): Calendar ID (default: 'primary'). description (Optional[str]): Event description. location (Optional[str]): Event location. attendees (Optional[List[str]]): Attendee email addresses. timezone (Optional[str]): Timezone (e.g., "America/New_York"). attachments (Optional[List[str]]): List of Google Drive file URLs or IDs to attach to the event. add_google_meet (bool): Whether to add a Google Meet video conference to the event. Defaults to False. reminders (Optional[Union[str, List[Dict[str, Any]]]]): JSON string or list of reminder objects. Each should have 'method' ("popup" or "email") and 'minutes' (0-40320). Max 5 reminders. Example: '[{"method": "popup", "minutes": 15}]' or [{"method": "popup", "minutes": 15}] use_default_reminders (bool): Whether to use calendar's default reminders. If False, uses custom reminders. Defaults to True. Returns: str: Confirmation message of the successful event creation with event link. """ logger.info( f"[create_event] Invoked. Email: '{user_google_email}', Summary: {summary}" ) logger.info(f"[create_event] Incoming attachments param: {attachments}") # If attachments value is a string, split by comma and strip whitespace if attachments and isinstance(attachments, str): attachments = [a.strip() for a in attachments.split(',') if a.strip()] logger.info(f"[create_event] Parsed attachments list from string: {attachments}") event_body: Dict[str, Any] = { "summary": summary, "start": ( {"date": start_time} if "T" not in start_time else {"dateTime": start_time} ), "end": ( {"date": end_time} if "T" not in end_time else {"dateTime": end_time} ), } if location: event_body["location"] = location if description: event_body["description"] = description if timezone: if "dateTime" in event_body["start"]: event_body["start"]["timeZone"] = timezone if "dateTime" in event_body["end"]: event_body["end"]["timeZone"] = timezone if attendees: event_body["attendees"] = [{"email": email} for email in attendees] # Handle reminders if reminders is not None or not use_default_reminders: # If custom reminders are provided, automatically disable default reminders effective_use_default = use_default_reminders and reminders is None reminder_data = { "useDefault": effective_use_default } if reminders is not None: validated_reminders = _parse_reminders_json(reminders, "create_event") if validated_reminders: reminder_data["overrides"] = validated_reminders logger.info(f"[create_event] Added {len(validated_reminders)} custom reminders") if use_default_reminders: logger.info("[create_event] Custom reminders provided - disabling default reminders") event_body["reminders"] = reminder_data if add_google_meet: request_id = str(uuid.uuid4()) event_body["conferenceData"] = { "createRequest": { "requestId": request_id, "conferenceSolutionKey": { "type": "hangoutsMeet" } } } logger.info(f"[create_event] Adding Google Meet conference with request ID: {request_id}") if attachments: # Accept both file URLs and file IDs. If a URL, extract the fileId. event_body["attachments"] = [] drive_service = None try: drive_service = service._http and build("drive", "v3", http=service._http) except Exception as e: logger.warning(f"Could not build Drive service for MIME type lookup: {e}") for att in attachments: file_id = None if att.startswith("https://"): # Match /d/<id>, /file/d/<id>, ?id=<id> match = re.search(r"(?:/d/|/file/d/|id=)([\w-]+)", att) file_id = match.group(1) if match else None logger.info(f"[create_event] Extracted file_id '{file_id}' from attachment URL '{att}'") else: file_id = att logger.info(f"[create_event] Using direct file_id '{file_id}' for attachment") if file_id: file_url = f"https://drive.google.com/open?id={file_id}" mime_type = "application/vnd.google-apps.drive-sdk" title = "Drive Attachment" # Try to get the actual MIME type and filename from Drive if drive_service: try: file_metadata = await asyncio.to_thread( lambda: drive_service.files().get(fileId=file_id, fields="mimeType,name").execute() ) mime_type = file_metadata.get("mimeType", mime_type) filename = file_metadata.get("name") if filename: title = filename logger.info(f"[create_event] Using filename '{filename}' as attachment title") else: logger.info("[create_event] No filename found, using generic title") except Exception as e: logger.warning(f"Could not fetch metadata for file {file_id}: {e}") event_body["attachments"].append({ "fileUrl": file_url, "title": title, "mimeType": mime_type, }) created_event = await asyncio.to_thread( lambda: service.events().insert( calendarId=calendar_id, body=event_body, supportsAttachments=True, conferenceDataVersion=1 if add_google_meet else 0 ).execute() ) else: created_event = await asyncio.to_thread( lambda: service.events().insert( calendarId=calendar_id, body=event_body, conferenceDataVersion=1 if add_google_meet else 0 ).execute() ) link = created_event.get("htmlLink", "No link available") confirmation_message = f"Successfully created event '{created_event.get('summary', summary)}' for {user_google_email}. Link: {link}" # Add Google Meet information if conference was created if add_google_meet and "conferenceData" in created_event: conference_data = created_event["conferenceData"] if "entryPoints" in conference_data: for entry_point in conference_data["entryPoints"]: if entry_point.get("entryPointType") == "video": meet_link = entry_point.get("uri", "") if meet_link: confirmation_message += f" Google Meet: {meet_link}" break logger.info( f"Event created successfully for {user_google_email}. ID: {created_event.get('id')}, Link: {link}" ) return confirmation_message
• gcalendar/calendar_tools.py:353-353 (registration)

  The @server.tool() decorator registers the create_event function as an MCP tool, with additional decorators for error handling and authentication.
  @server.tool()
• gcalendar/calendar_tools.py:28-85 (helper)

  Helper utility to parse and validate custom reminders input (JSON string or list) used in create_event for setting event reminders.
  def _parse_reminders_json(reminders_input: Optional[Union[str, List[Dict[str, Any]]]], function_name: str) -> List[Dict[str, Any]]: """ Parse reminders from JSON string or list object and validate them. Args: reminders_input: JSON string containing reminder objects or list of reminder objects function_name: Name of calling function for logging Returns: List of validated reminder objects """ if not reminders_input: return [] # Handle both string (JSON) and list inputs if isinstance(reminders_input, str): try: reminders = json.loads(reminders_input) if not isinstance(reminders, list): logger.warning(f"[{function_name}] Reminders must be a JSON array, got {type(reminders).__name__}") return [] except json.JSONDecodeError as e: logger.warning(f"[{function_name}] Invalid JSON for reminders: {e}") return [] elif isinstance(reminders_input, list): reminders = reminders_input else: logger.warning(f"[{function_name}] Reminders must be a JSON string or list, got {type(reminders_input).__name__}") return [] # Validate reminders if len(reminders) > 5: logger.warning(f"[{function_name}] More than 5 reminders provided, truncating to first 5") reminders = reminders[:5] validated_reminders = [] for reminder in reminders: if not isinstance(reminder, dict) or "method" not in reminder or "minutes" not in reminder: logger.warning(f"[{function_name}] Invalid reminder format: {reminder}, skipping") continue method = reminder["method"].lower() if method not in ["popup", "email"]: logger.warning(f"[{function_name}] Invalid reminder method '{method}', must be 'popup' or 'email', skipping") continue minutes = reminder["minutes"] if not isinstance(minutes, int) or minutes < 0 or minutes > 40320: logger.warning(f"[{function_name}] Invalid reminder minutes '{minutes}', must be integer 0-40320, skipping") continue validated_reminders.append({ "method": method, "minutes": minutes }) return validated_reminders
• gcalendar/calendar_tools.py:372-392 (schema)

  The docstring provides the input schema and descriptions for the create_event tool parameters.
  """ Creates a new event. Args: user_google_email (str): The user's Google email address. Required. summary (str): Event title. start_time (str): Start time (RFC3339, e.g., "2023-10-27T10:00:00-07:00" or "2023-10-27" for all-day). end_time (str): End time (RFC3339, e.g., "2023-10-27T11:00:00-07:00" or "2023-10-28" for all-day). calendar_id (str): Calendar ID (default: 'primary'). description (Optional[str]): Event description. location (Optional[str]): Event location. attendees (Optional[List[str]]): Attendee email addresses. timezone (Optional[str]): Timezone (e.g., "America/New_York"). attachments (Optional[List[str]]): List of Google Drive file URLs or IDs to attach to the event. add_google_meet (bool): Whether to add a Google Meet video conference to the event. Defaults to False. reminders (Optional[Union[str, List[Dict[str, Any]]]]): JSON string or list of reminder objects. Each should have 'method' ("popup" or "email") and 'minutes' (0-40320). Max 5 reminders. Example: '[{"method": "popup", "minutes": 15}]' or [{"method": "popup", "minutes": 15}] use_default_reminders (bool): Whether to use calendar's default reminders. If False, uses custom reminders. Defaults to True. Returns: str: Confirmation message of the successful event creation with event link. """