MCP Google Contacts Server

Instructions

    Args:
        name_filter: Optional filter to find contacts by name
        max_results: Maximum number of results to return (default: 100)
    

Implementation Reference

• mcp_google_contacts_server/tools.py:61-78 (handler)

  The main MCP tool handler for 'list_contacts'. It uses FastMCP's @tool decorator for registration and schema inference from type hints and docstring. Initializes service, calls the core list_contacts method, formats output with format_contacts_list, and handles errors.

  @mcp.tool()
  async def list_contacts(name_filter: Optional[str] = None, max_results: int = 100) -> str:
      """List all contacts or filter by name.
      
      Args:
          name_filter: Optional filter to find contacts by name
          max_results: Maximum number of results to return (default: 100)
      """
      service = init_service()
      if not service:
          return "Error: Google Contacts service is not available. Please check your credentials."
      
      try:
          contacts = service.list_contacts(name_filter, max_results)
          return format_contacts_list(contacts)
      except Exception as e:
          return f"Error: Failed to list contacts - {str(e)}"

• mcp_google_contacts_server/google_contacts_service.py:157-223 (helper)

  Core helper method in GoogleContactsService that implements the actual API call to list contacts using Google People API v1. Supports name filtering and pagination limits, extracts and formats contact fields (names, emails, phones).

  def list_contacts(self, name_filter: Optional[str] = None, 
                   max_results: int = None) -> List[Dict[str, Any]]:
      """List contacts, optionally filtering by name.
      
      Args:
          name_filter: Optional filter to find contacts by name
          max_results: Maximum number of results to return
          
      Returns:
          List of contact dictionaries
          
      Raises:
          GoogleContactsError: If API request fails
      """
      max_results = max_results or config.default_max_results
      
      try:
          # Get list of connections (contacts)
          results = self.service.people().connections().list(
              resourceName='people/me',
              pageSize=max_results,
              personFields='names,emailAddresses,phoneNumbers',
              sortOrder='FIRST_NAME_ASCENDING'
          ).execute()
          
          connections = results.get('connections', [])
          
          if not connections:
              return []
          
          contacts = []
          for person in connections:
              names = person.get('names', [])
              if not names:
                  continue
              
              name = names[0]
              given_name = name.get('givenName', '')
              family_name = name.get('familyName', '')
              display_name = name.get('displayName', '')
              
              # Apply name filter if provided
              if name_filter and name_filter.lower() not in display_name.lower():
                  continue
              
              # Get email addresses
              emails = person.get('emailAddresses', [])
              email = emails[0].get('value') if emails else None
              
              # Get phone numbers
              phones = person.get('phoneNumbers', [])
              phone = phones[0].get('value') if phones else None
              
              contacts.append({
                  'resourceName': person.get('resourceName'),
                  'givenName': given_name,
                  'familyName': family_name,
                  'displayName': display_name,
                  'email': email,
                  'phone': phone
              })
          
          return contacts
      
      except HttpError as error:
          raise GoogleContactsError(f"Error listing contacts: {error}")

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

  Invocation of register_tools(mcp) in the main server entrypoint, which defines and registers the list_contacts tool using the @mcp.tool() decorator.

  # Register all tools
  register_tools(mcp)