Google Contacts: Search contacts — MCP tool
Google Contacts MCP tool: Full-text prefix search over the user's saved contacts by names, emails, phones and organizations.
Technical name: search_contacts
What task it solves
I want to find a contact by name, email or phone.
Searches the saved contacts by names, nicknames, email addresses, phone numbers and organizations with prefix matching ("jo" finds "John").
When to use it
Use it to look up a specific person before reading, updating, grouping or deleting them. For full exports or just-created contacts use List contacts.
What to provide
query— required. The search text.read_mask— optional. Fields to return; defaultnames, emailAddresses, phoneNumbers, organizations, memberships.page_size— optional. Max matches, 1..30 (default 10).
What it returns
results[], each with a person carrying resourceName, etag and only the masked fields.
What changes in Google Contacts
The tool reads Google Contacts data and does not change it.
Example request
Find the contact whose email starts with "ada@".
Errors and limitations
Max 30 results and no pagination. The search cache lags writes by a few seconds and goes cold between sessions — the documented warmup request is sent automatically before the session's first search, but a contact created seconds ago may still be missing (fall back to list_contacts). "Other contacts" are not searched here. Access also depends on token permissions, quotas, and upstream API limits.
Related MCP tools
- List contacts —
list_contacts - Get a contact —
get_contact - List or search Other contacts —
list_other_contacts
Technical details
- Impact: read-only
- Group: Contacts
- Description source:
search_contactsregistration insrc/tools/contacts.ts - Full technical reference
- All MCP capabilities