MCP Google Contacts Server

Instructions

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)