MCP Google Contacts Server

Instructions

    Args:
        resource_name: Contact group resource name (e.g., "contactGroups/12345")
        include_members: Whether to include the list of member contact IDs
        max_members: Maximum number of member IDs to return if include_members is True
    

Implementation Reference

• src/tools.py:455-474 (handler)

  The MCP tool handler implementation for 'get_contact_group', decorated with @mcp.tool(). It initializes the service, fetches the group, and formats the output.

  async def get_contact_group(
      resource_name: str, include_members: bool = False, max_members: int = 50
  ) -> str:
      """Get detailed information about a specific contact group.
  
      Args:
          resource_name: Contact group resource name (e.g., "contactGroups/12345")
          include_members: Whether to include the list of member contact IDs
          max_members: Maximum number of member IDs to return if include_members is True
      """
      service = init_service()
      if not service:
          return "Error: Google Contacts service is not available. Please check your credentials."
  
      try:
          max_members_param = max_members if include_members else 0
          group = service.get_contact_group(resource_name, max_members_param)
          return format_contact_group(group)
      except Exception as e:
          return f"Error: Failed to get contact group - {str(e)}"

• src/google_contacts_service.py:1135-1158 (helper)

  The core service method that performs the actual API call to retrieve contact group details from Google Contacts API.

  def get_contact_group(self, resource_name: str, max_members: int = 0) -> Dict[str, Any]:
      """Get a specific contact group by resource name.
  
      Args:
          resource_name: Contact group resource name (contactGroups/*)
          max_members: Maximum number of members to return (0 for metadata only)
  
      Returns:
          Contact group dictionary with member details
      """
      try:
          params = {}
          if max_members > 0:
              params["maxMembers"] = max_members
  
          response = (
              self.service.contactGroups().get(resourceName=resource_name, **params).execute()
          )
  
          return self._format_contact_group(response, include_members=max_members > 0)
  
      except HttpError as error:
          raise GoogleContactsError(f"Error getting contact group: {error}")

• src/formatters.py:472-535 (helper)

  Helper function to format the contact group data into a human-readable string, used by the handler.

  def format_contact_group(group: Dict[str, Any]) -> str:
      """Format a contact group dictionary into a readable string.
  
      Args:
          group: Dictionary containing contact group information
  
      Returns:
          Formatted string representation of the contact group
      """
      if not group:
          return "No contact group data available"
  
      parts = []
  
      # Group name and type
      name = group.get("name", "Unnamed Group")
      group_type = group.get("groupType", "").replace("_", " ").title()
      if group_type:
          parts.append("📂 " + name + " (" + group_type + ")")
      else:
          parts.append("📂 " + name)
  
      # Member count
      member_count = group.get("memberCount", 0)
      if member_count > 0:
          parts.append("👥 Members: " + str(member_count))
      else:
          parts.append("👥 Members: None")
  
      # Update time
      if group.get("updateTime"):
          parts.append("🕒 Last Updated: " + group["updateTime"])
  
      # Resource ID
      if group.get("resourceName"):
          parts.append("🔗 ID: " + group["resourceName"])
  
      # Client data
      if group.get("clientData"):
          client_data_parts = []
          for data in group["clientData"]:
              key = data.get("key", "")
              value = data.get("value", "")
              if key and value:
                  client_data_parts.append("   • " + key + ": " + value)
          if client_data_parts:
              parts.append("🔧 Custom Data:\n" + "\n".join(client_data_parts))
  
      # Member resource names (if included)
      if group.get("memberResourceNames"):
          member_names = group["memberResourceNames"]
          if len(member_names) <= 5:
              parts.append("📋 Member IDs: " + ", ".join(member_names))
          else:
              parts.append(
                  "📋 Member IDs: "
                  + ", ".join(member_names[:5])
                  + " ... (and "
                  + str(len(member_names) - 5)
                  + " more)"
              )
  
      return "\n".join(parts)

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

  Top-level registration function called from main.py that includes registration of contact group tools containing 'get_contact_group'.

  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)

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

  Call in main.py to register all tools via the register_tools function.

  register_tools(mcp)