Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Instructions

Implementation Reference

• gdrive/drive_tools.py:35-100 (handler)

  Primary handler function for the 'search_drive_files' tool. Decorated for registration, error handling, and auth. Parses query (structured or free-text), builds API params via helper, executes Drive files.list(), formats results as readable text list.
  @server.tool() @handle_http_errors("search_drive_files", is_read_only=True, service_type="drive") @require_google_service("drive", "drive_read") async def search_drive_files( service, user_google_email: str, query: str, page_size: int = 10, drive_id: Optional[str] = None, include_items_from_all_drives: bool = True, corpora: Optional[str] = None, ) -> str: """ Searches for files and folders within a user's Google Drive, including shared drives. Args: user_google_email (str): The user's Google email address. Required. query (str): The search query string. Supports Google Drive search operators. page_size (int): The maximum number of files to return. Defaults to 10. drive_id (Optional[str]): ID of the shared drive to search. If None, behavior depends on `corpora` and `include_items_from_all_drives`. include_items_from_all_drives (bool): Whether shared drive items should be included in results. Defaults to True. This is effective when not specifying a `drive_id`. corpora (Optional[str]): Bodies of items to query (e.g., 'user', 'domain', 'drive', 'allDrives'). If 'drive_id' is specified and 'corpora' is None, it defaults to 'drive'. Otherwise, Drive API default behavior applies. Prefer 'user' or 'drive' over 'allDrives' for efficiency. Returns: str: A formatted list of found files/folders with their details (ID, name, type, size, modified time, link). """ logger.info(f"[search_drive_files] Invoked. Email: '{user_google_email}', Query: '{query}'") # Check if the query looks like a structured Drive query or free text # Look for Drive API operators and structured query patterns is_structured_query = any(pattern.search(query) for pattern in DRIVE_QUERY_PATTERNS) if is_structured_query: final_query = query logger.info(f"[search_drive_files] Using structured query as-is: '{final_query}'") else: # For free text queries, wrap in fullText contains escaped_query = query.replace("'", "\\'") final_query = f"fullText contains '{escaped_query}'" logger.info(f"[search_drive_files] Reformatting free text query '{query}' to '{final_query}'") list_params = build_drive_list_params( query=final_query, page_size=page_size, drive_id=drive_id, include_items_from_all_drives=include_items_from_all_drives, corpora=corpora, ) results = await asyncio.to_thread( service.files().list(**list_params).execute ) files = results.get('files', []) if not files: return f"No files found for '{query}'." formatted_files_text_parts = [f"Found {len(files)} files for {user_google_email} matching '{query}':"] for item in files: size_str = f", Size: {item.get('size', 'N/A')}" if 'size' in item else "" formatted_files_text_parts.append( f"- Name: \"{item['name']}\" (ID: {item['id']}, Type: {item['mimeType']}{size_str}, Modified: {item.get('modifiedTime', 'N/A')}) Link: {item.get('webViewLink', '#')}" ) text_output = "\n".join(formatted_files_text_parts) return text_output
• gdrive/drive_tools.py:47-62 (schema)

  Docstring defining input parameters, types, defaults, and return format, serving as the tool schema for MCP.
  """ Searches for files and folders within a user's Google Drive, including shared drives. Args: user_google_email (str): The user's Google email address. Required. query (str): The search query string. Supports Google Drive search operators. page_size (int): The maximum number of files to return. Defaults to 10. drive_id (Optional[str]): ID of the shared drive to search. If None, behavior depends on `corpora` and `include_items_from_all_drives`. include_items_from_all_drives (bool): Whether shared drive items should be included in results. Defaults to True. This is effective when not specifying a `drive_id`. corpora (Optional[str]): Bodies of items to query (e.g., 'user', 'domain', 'drive', 'allDrives'). If 'drive_id' is specified and 'corpora' is None, it defaults to 'drive'. Otherwise, Drive API default behavior applies. Prefer 'user' or 'drive' over 'allDrives' for efficiency. Returns: str: A formatted list of found files/folders with their details (ID, name, type, size, modified time, link). """
• gdrive/drive_tools.py:35-37 (registration)

  Tool registration via @server.tool() decorator, plus error handler and auth requirement decorators specific to this tool.
  @server.tool() @handle_http_errors("search_drive_files", is_read_only=True, service_type="drive") @require_google_service("drive", "drive_read")
• gdrive/drive_helpers.py:74-112 (helper)

  Helper constructs standardized parameters for Drive files.list() API calls, handling shared drives (driveId/corpora) and common fields.
  def build_drive_list_params( query: str, page_size: int, drive_id: Optional[str] = None, include_items_from_all_drives: bool = True, corpora: Optional[str] = None, ) -> Dict[str, Any]: """ Helper function to build common list parameters for Drive API calls. Args: query: The search query string page_size: Maximum number of items to return drive_id: Optional shared drive ID include_items_from_all_drives: Whether to include items from all drives corpora: Optional corpus specification Returns: Dictionary of parameters for Drive API list calls """ list_params = { "q": query, "pageSize": page_size, "fields": "nextPageToken, files(id, name, mimeType, webViewLink, iconLink, modifiedTime, size)", "supportsAllDrives": True, "includeItemsFromAllDrives": include_items_from_all_drives, } if drive_id: list_params["driveId"] = drive_id if corpora: list_params["corpora"] = corpora else: list_params["corpora"] = "drive" elif corpora: list_params["corpora"] = corpora return list_params
• gdrive/drive_helpers.py:59-71 (helper)

  Regex patterns used to identify structured Drive search queries vs free-text, triggering query reformatting in handler.
  DRIVE_QUERY_PATTERNS = [ re.compile(r'\b\w+\s*(=|!=|>|<)\s*[\'"].*?[\'"]', re.IGNORECASE), # field = 'value' re.compile(r'\b\w+\s*(=|!=|>|<)\s*\d+', re.IGNORECASE), # field = number re.compile(r'\bcontains\b', re.IGNORECASE), # contains operator re.compile(r'\bin\s+parents\b', re.IGNORECASE), # in parents re.compile(r'\bhas\s*\{', re.IGNORECASE), # has {properties} re.compile(r'\btrashed\s*=\s*(true|false)\b', re.IGNORECASE), # trashed=true/false re.compile(r'\bstarred\s*=\s*(true|false)\b', re.IGNORECASE), # starred=true/false re.compile(r'[\'"][^\'"]+[\'"]\s+in\s+parents', re.IGNORECASE), # 'parentId' in parents re.compile(r'\bfullText\s+contains\b', re.IGNORECASE), # fullText contains re.compile(r'\bname\s*(=|contains)\b', re.IGNORECASE), # name = or name contains re.compile(r'\bmimeType\s*(=|!=)\b', re.IGNORECASE), # mimeType operators ]