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)
        include_all_fields: Whether to include all contact fields like addresses, birthdays, etc.
    

Implementation Reference

• src/tools.py:78-98 (handler)

  Handler function for the list_contacts tool, decorated with @mcp.tool() for registration. Includes parameter schema via type hints and docstring. Executes the tool logic by calling the service.

  @mcp.tool()
  async def list_contacts(
      name_filter: Optional[str] = None, max_results: int = 100, include_all_fields: bool = False
  ) -> str:
      """List all contacts or filter by name with comprehensive field support.
  
      Args:
          name_filter: Optional filter to find contacts by name
          max_results: Maximum number of results to return (default: 100)
          include_all_fields: Whether to include all contact fields like addresses, birthdays, etc.
      """
      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, include_all_fields)
          return format_contacts_list(contacts)
      except Exception as e:
          return f"Error: Failed to list contacts - {str(e)}"

• src/google_contacts_service.py:199-272 (helper)

  GoogleContactsService.list_contacts method: the primary helper that performs the Google People API calls to list and filter contacts.

  def list_contacts(
      self,
      name_filter: Optional[str] = None,
      max_results: int = None,
      include_all_fields: bool = False,
  ) -> List[Dict[str, Any]]:
      """List contacts, optionally filtering by name with pagination support.
  
      Args:
          name_filter: Optional filter to find contacts by name
          max_results: Maximum number of results to return
          include_all_fields: Whether to include all contact fields
  
      Returns:
          List of contact dictionaries
  
      Raises:
          GoogleContactsError: If API request fails
      """
      max_results = max_results or config.default_max_results
  
      try:
          contacts = []
          next_page_token = None
  
          # Use extended fields if requested
          person_fields = (
              ",".join(self.PERSON_FIELDS)
              if include_all_fields
              else "names,emailAddresses,phoneNumbers,addresses,organizations,birthdays,urls,biographies,relations,nicknames"
          )
  
          while len(contacts) < max_results:
              page_size = min(1000, max_results - len(contacts))  # Google API limit is 1000
  
              request_params = {
                  "resourceName": "people/me",
                  "pageSize": page_size,
                  "personFields": person_fields,
                  "sortOrder": "DISPLAY_NAME_ASCENDING",
              }
  
              if next_page_token:
                  request_params["pageToken"] = next_page_token
  
              results = self.service.people().connections().list(**request_params).execute()
  
              connections = results.get("connections", [])
              if not connections:
                  break
  
              for person in connections:
                  contact = self._format_contact_enhanced(person)
  
                  # Apply name filter if provided
                  if name_filter:
                      filter_lower = name_filter.lower()
                      if not any(
                          filter_lower in str(contact.get(field, "")).lower()
                          for field in ["displayName", "givenName", "familyName", "nickname"]
                      ):
                          continue
  
                  contacts.append(contact)
  
                  if len(contacts) >= max_results:
                      break
  
              next_page_token = results.get("nextPageToken")
              if not next_page_token:
                  break
  
          return contacts

• src/formatters.py:273-307 (helper)

  format_contacts_list function: formats the list of contacts into a human-readable string output.

  def format_contacts_list(contacts: List[Dict[str, Any]]) -> str:
      """Format a list of contacts into a readable string with enhanced display.
  
      Args:
          contacts: List of contact dictionaries
  
      Returns:
          Formatted string representation of the contacts list
      """
      if not contacts:
          return "No contacts found."
  
      if isinstance(contacts, dict) and "status" in contacts and contacts["status"] == "error":
          return "Error: " + contacts.get("message", "Unknown error")
  
      parts = []
  
      for i, contact in enumerate(contacts, 1):
          # Create a compact summary for lists
          contact_summary = _format_contact_summary(contact, i)
          parts.append(contact_summary)
          parts.append("")  # Add blank line between contacts
  
      summary = "📊 Found " + str(len(contacts)) + " contact(s)"
  
      # Add statistics
      stats = _calculate_contact_stats(contacts)
      if stats:
          summary += "\n📈 Statistics: " + stats
  
      parts.append("=" * 50)
      parts.append(summary)
  
      return "\n".join(parts)

• src/tools.py:64-75 (registration)

  register_tools function that orchestrates calling register_contact_tools(mcp), which defines and registers the list_contacts tool.

  def register_tools(mcp: FastMCP) -> None:
      """Register all Google Contacts tools with the MCP server.
  
      Args:
          mcp: FastMCP server instance
      """
      register_contact_tools(mcp)
      register_directory_tools(mcp)
      register_contact_group_tools(mcp)
  
  
  def register_contact_tools(mcp: FastMCP) -> None:

• src/main.py:71-75 (registration)

  In main(), creation of FastMCP server and call to register_tools(mcp) to register all tools including list_contacts.

  mcp = FastMCP("google-contacts")
  
  # Register all tools
  register_tools(mcp)