MCP Google Contacts Server

Instructions

    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)
    

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