list_contacts
Retrieve contacts from your Google account with optional name filtering to find specific individuals quickly.
Instructions
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)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name_filter | No | ||
| max_results | No |
Implementation Reference
- 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)}"
- 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)