list_contacts
Retrieve and filter Google Contacts by name with custom results limit. Use to access and organize contact lists efficiently within your Google account.
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
| Name | Required | Description | Default |
|---|---|---|---|
| max_results | No | ||
| name_filter | No |
Input Schema (JSON Schema)
{
"properties": {
"max_results": {
"default": 100,
"title": "Max Results",
"type": "integer"
},
"name_filter": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"title": "Name Filter"
}
},
"title": "list_contactsArguments",
"type": "object"
}
Implementation Reference
- The main handler function for the 'list_contacts' MCP tool. It initializes the service, calls the service's list_contacts method, formats the result, and handles errors. The @mcp.tool() decorator registers the tool with the FastMCP server.@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)}"
- Helper method in GoogleContactsService that performs the actual API call to list contacts from Google People API, applies filtering, and formats the response.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-85 (registration)Call to register_tools which defines and registers the list_contacts tool (and others) via @mcp.tool() decorators.# Register all tools register_tools(mcp)
- Function signature and docstring defining the input schema (parameters with types and descriptions) and output (str). Used by MCP for tool schema.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) """