MCP Google Contacts Server

Instructions

    This is useful for seeing which contacts have a particular label assigned.

    Args:
        group_resource_name: Contact group resource name (e.g., "contactGroups/12345")
        max_results: Maximum number of contacts to return
    

Implementation Reference

• src/tools.py:557-596 (handler)

  Core handler function for the 'search_contacts_by_group' tool. It uses the Google Contacts service to retrieve group members and their contact details, then formats and returns the list.

  @mcp.tool()
  async def search_contacts_by_group(group_resource_name: str, max_results: int = 50) -> str:
      """Find all contacts that belong to a specific contact group.
  
      This is useful for seeing which contacts have a particular label assigned.
  
      Args:
          group_resource_name: Contact group resource name (e.g., "contactGroups/12345")
          max_results: Maximum number of contacts to return
      """
      service = init_service()
      if not service:
          return "Error: Google Contacts service is not available. Please check your credentials."
  
      try:
          # Get the group with member resource names
          group = service.get_contact_group(group_resource_name, max_results)
  
          if not group.get("memberResourceNames"):
              return f"No contacts found in group '{group.get('name', 'Unknown Group')}'"
  
          # Get full contact details for each member
          member_contacts = []
          for member_resource_name in group["memberResourceNames"]:
              try:
                  contact = service.get_contact(member_resource_name, include_all_fields=False)
                  member_contacts.append(contact)
              except Exception:
                  # Skip contacts that can't be retrieved
                  continue
  
          if not member_contacts:
              return (
                  f"No accessible contacts found in group '{group.get('name', 'Unknown Group')}'"
              )
  
          group_name = group.get("name", "Unknown Group")
          return f"Contacts in group '{group_name}':\n\n{format_contacts_list(member_contacts)}"
      except Exception as e:
          return f"Error: Failed to search contacts by group - {str(e)}"

• src/main.py:73-74 (registration)

  Calls register_tools(mcp) which registers the search_contacts_by_group tool (along with others) to the MCP server.

  # Register all tools
  register_tools(mcp)

• src/tools.py:70-72 (registration)

  The register_tools function calls register_contact_group_tools(mcp), where the search_contacts_by_group tool is defined and registered via @mcp.tool() decorator.

  register_contact_tools(mcp)
  register_directory_tools(mcp)
  register_contact_group_tools(mcp)

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

  Helper function used by the tool to format the list of contacts retrieved from the group.

  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