list_workspace_users
Search and list Google Workspace users in your organization's directory to find email addresses and contact information.
Instructions
List Google Workspace users in your organization's directory.
This tool allows you to search and list users in your Google Workspace directory,
including their email addresses and other information.
Args:
query: Optional search term to find specific users (name, email, etc.)
max_results: Maximum number of results to return (default: 50)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| max_results | No |
Implementation Reference
- src/tools.py:342-362 (handler)The handler function for the 'list_workspace_users' tool, decorated with @mcp.tool() for automatic registration. It initializes the GoogleContactsService, calls list_directory_people on it, and formats the result using format_directory_people. The docstring and type hints define the tool schema.
@mcp.tool() async def list_workspace_users(query: Optional[str] = None, max_results: int = 50) -> str: """List Google Workspace users in your organization's directory. This tool allows you to search and list users in your Google Workspace directory, including their email addresses and other information. Args: query: Optional search term to find specific users (name, email, etc.) max_results: Maximum number of results to return (default: 50) """ service = init_service() if not service: return "Error: Google Contacts service is not available. Please check your credentials." try: workspace_users = service.list_directory_people(query=query, max_results=max_results) return format_directory_people(workspace_users, query) except Exception as e: return f"Error: Failed to list Google Workspace users - {str(e)}" - Core helper method implementing the Google People API calls (searchDirectoryPeople or listDirectoryPeople) to retrieve Workspace directory users, formats them using _format_directory_person, and handles errors.
def list_directory_people( self, query: Optional[str] = None, max_results: int = 50 ) -> List[Dict]: """List people from the Google Workspace directory. Args: query: Optional search query to filter directory results max_results: Maximum number of results to return Returns: List of formatted directory contact dictionaries """ try: # Check if directory API access is available directory_fields = "names,emailAddresses,organizations,phoneNumbers" # Build the request, with or without a query if query: request = self.service.people().searchDirectoryPeople( query=query, readMask=directory_fields, sources=[ "DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT", "DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE", ], pageSize=max_results, ) else: request = self.service.people().listDirectoryPeople( readMask=directory_fields, sources=[ "DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT", "DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE", ], pageSize=max_results, ) # Execute the request response = request.execute() print("response; ", response) # Process the results people = response.get("people", []) if not people: return [] # Format each person entry directory_contacts = [] for person in people: contact = self._format_directory_person(person) directory_contacts.append(contact) return directory_contacts - src/formatters.py:382-421 (helper)Helper function to format the output of directory people list into a user-friendly string, including summaries and statistics.
def format_directory_people(people: List[Dict[str, Any]], query: Optional[str] = None) -> str: """Format a list of directory people into a readable string with enhanced display. Args: people: List of directory people dictionaries query: Optional search query used to find these people Returns: Formatted string representation of the directory people """ if not people: if query: return "No directory members found matching '" + query + "'." return "No directory members found." # Count how many users have emails users_with_email = _count_users_with_email(people) # Format the results formatted_users = [] for i, user in enumerate(people, 1): user_parts = _format_single_directory_user(user, i) formatted_users.append("\n".join(user_parts)) # Add summary query_part = " matching '" + query + "'" if query else "" summary = ( "📊 Found " + str(len(people)) + " directory member(s)" + query_part + ". " + str(users_with_email) + " have email addresses." ) formatted_users.append("=" * 50) formatted_users.append(summary) return "\n\n".join(formatted_users) - src/tools.py:23-62 (helper)Helper function to initialize the global GoogleContactsService instance, trying env vars then credential files.
def init_service() -> Optional[GoogleContactsService]: """Initialize and return a Google Contacts service instance. Returns: GoogleContactsService instance or None if initialization fails """ global contacts_service if contacts_service: return contacts_service try: # First try environment variables try: contacts_service = GoogleContactsService.from_env() print("Successfully loaded credentials from environment variables.") return contacts_service except GoogleContactsError: pass # Then try default file locations for path in config.credentials_paths: if path.exists(): try: print(f"Found credentials file at {path}") contacts_service = GoogleContactsService.from_file(path) print("Successfully loaded credentials from file.") return contacts_service except GoogleContactsError as e: print(f"Error with credentials at {path}: {e}") continue print("No valid credentials found. Please provide credentials to use Google Contacts.") return None except Exception as e: print(f"Error initializing Google Contacts service: {str(e)}") traceback.print_exc() return None