MCP Google Contacts Server

Instructions

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)}"
• src/google_contacts_service.py:505-558 (helper)

  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