MCP Google Contacts Server

Instructions

    Args:
        identifier: Resource name (people/*) or email address of the contact
    

Implementation Reference

• mcp_google_contacts_server/tools.py:79-94 (handler)

  The main MCP tool handler for 'get_contact'. This async function is decorated with @mcp.tool() for automatic registration. It initializes the GoogleContactsService, calls service.get_contact(identifier), formats the contact with format_contact, and returns the formatted string or an error message.

  @mcp.tool()
  async def get_contact(identifier: str) -> str:
      """Get a contact by resource name or email.
      
      Args:
          identifier: Resource name (people/*) or email address of the contact
      """
      service = init_service()
      if not service:
          return "Error: Google Contacts service is not available. Please check your credentials."
      
      try:
          contact = service.get_contact(identifier)
          return format_contact(contact)
      except Exception as e:
          return f"Error: Failed to get contact - {str(e)}"

• mcp_google_contacts_server/google_contacts_service.py:224-280 (helper)

  Core helper method in GoogleContactsService that implements the contact retrieval logic using Google People API v1. Handles both resourceName lookups and email-based searches (falling back to directory if enabled). Returns formatted contact dict or raises error.

  def get_contact(self, identifier: str, include_email: bool = True, 
                 use_directory_api: bool = False) -> Dict[str, Any]:
      """Get a contact by resource name or email.
      
      Args:
          identifier: Resource name (people/*) or email address
          include_email: Whether to include email addresses
          use_directory_api: Whether to try the directory API as well
          
      Returns:
          Contact dictionary
          
      Raises:
          GoogleContactsError: If contact cannot be found or API request fails
      """
      try:
          if identifier.startswith('people/'):
              # Determine which API to use based on parameters
              if use_directory_api:
                  # For directory contacts
                  try:
                      person = self.service.people().people().get(
                          resourceName=identifier,
                          personFields='names,emailAddresses,phoneNumbers,organizations'
                      ).execute()
                  except HttpError:
                      # Fall back to standard contacts API if directory API fails
                      person = self.service.people().get(
                          resourceName=identifier,
                          personFields='names,emailAddresses,phoneNumbers'
                      ).execute()
              else:
                  # Standard contacts API
                  person = self.service.people().get(
                      resourceName=identifier,
                      personFields='names,emailAddresses,phoneNumbers'
                  ).execute()
              
              return self._format_contact(person)
          else:
              # Assume it's an email address and search for it
              contacts = self.list_contacts()
              for contact in contacts:
                  if contact.get('email') == identifier:
                      return contact
              
              # If not found in regular contacts, try directory
              if use_directory_api:
                  directory_users = self.list_directory_people(query=identifier, max_results=1)
                  if directory_users:
                      return directory_users[0]
              
              raise GoogleContactsError(f"Contact with email {identifier} not found")
      
      except HttpError as error:
          raise GoogleContactsError(f"Error getting contact: {error}")

• mcp_google_contacts_server/main.py:83-84 (registration)

  In main.py, register_tools(mcp) is called on the FastMCP server instance. This invokes the register_tools function from tools.py, which defines the get_contact handler with @mcp.tool() decorator, thereby registering the tool.

  # Register all tools
  register_tools(mcp)