Google Contacts

Google Contacts

This connector reads and manages the signed-in user's Google Contacts through the Google People API v1 (https://people.googleapis.com/v1): it lists and searches contacts, reads one in full, creates and updates contacts, manages contact groups (labels), and reads the "Other contacts" Google saves from email. It works with personal Google accounts and Google Workspace, as the Google account that authorized the connector. The Workspace company directory is not included.

Setup (one-time, about 10 minutes)

1. Open https://console.cloud.google.com, pick or create a project, then APIs & Services → Library → enable Google People API.
2. APIs & Services → OAuth consent screen: choose Internal if you are on Google Workspace (simplest), otherwise External. For External, set the publishing status to In production: while an app is in Testing, Google revokes its refresh tokens after 7 days and the connector stops working every week. For your own use, the "unverified app" warning can be clicked through.
3. APIs & Services → Credentials → Create credentials → OAuth client ID → application type Web application → add the authorized redirect URI <your AnythingMCP URL>/api/mcp-oauth/callback (on AnythingMCP Cloud: https://cloud.anythingmcp.com/api/mcp-oauth/callback).
4. Paste the client ID and secret into GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET and install the connector.
5. On the connector page, click Authorize with Provider and sign in with the Google account whose contacts the AI should use. The refresh token is stored encrypted and access tokens are renewed automatically.

One Google client for all Google connectors: the same Cloud project and OAuth client can serve every Google connector (Gmail, Google Calendar, Google Drive, Google Sheets, Google Docs, Google Slides, Google Forms, Google Contacts, Google Tasks, Search Console, Analytics, Ads). Enable each API in that project, reuse the same GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET, and authorize each connector once: each one asks only for its own scopes.

Scopes: the connector asks for https://www.googleapis.com/auth/contacts (read and edit the user's contacts and labels) and https://www.googleapis.com/auth/contacts.other.readonly (read "Other contacts"). Both are sensitive scopes: outside your own Workspace organisation Google shows the unverified-app warning until the app is verified. For a read-only setup, change the scopes to https://www.googleapis.com/auth/contacts.readonly https://www.googleapis.com/auth/contacts.other.readonly in the connector's OAuth settings, authorize again, and disable google_contacts_create_contact, google_contacts_update_contact, google_contacts_create_contact_group, google_contacts_modify_group_members and google_contacts_save_other_contact. Without "Other contacts", drop the second scope and disable google_contacts_list_other_contacts, google_contacts_search_other_contacts and google_contacts_save_other_contact.

Switched off at install: google_contacts_delete_contact. Turn it on if the AI should delete contacts.

Before every change: show the user the contact and the change, and wait for a yes. Contacts sync to the user's phone and Gmail at once.

Ids: a contact's resourceName is people/<id>; tools take the part after people/ as person_id. Groups are contactGroups/<id> (myContacts, starred or a label's id) and other contacts otherContacts/<id>.

Finding people

• google_contacts_search_contacts matches the beginning of names, emails, phone numbers and organizations. It reads a cache that Google refreshes on request: call google_contacts_warm_up_search once before the first search of a session, wait a few seconds, then search. If a contact created minutes ago is missing, warm up again or list with google_contacts_list_contacts and sort_order LAST_MODIFIED_DESCENDING.
• google_contacts_list_contacts pages through everything; ask only for the fields you need (person_fields).
• "Other contacts" (google_contacts_list_other_contacts, google_contacts_search_other_contacts, warm up with search otherContacts:search) are addresses the user emailed but never saved; google_contacts_save_other_contact copies one into My Contacts.
• Answers leave out Google's per-entry metadata (source and primary flags) and are cut at 200 KB.

Writing

• google_contacts_create_contact takes lists in People API form, e.g. names [{"givenName": "Ana", "familyName": "García"}], email_addresses [{"value": "[email protected]", "type": "work"}]. Names, notes (biographies) and birthdays hold one entry each. Google does not prevent duplicates: search first.
• google_contacts_update_contact replaces each field named in update_person_fields as a whole, so read the contact first and send the full new list. It needs the contact's current etag; after an update, use the etag from the reply for the next one.
• Send changes for the same user one after the other, not in parallel: Google asks for this and may otherwise fail or slow down. Changes can take a few minutes to show up in lists and search.
• Labels: google_contacts_create_contact_group, then google_contacts_modify_group_members with resourceNames. Removing a contact from a label keeps the contact.
• google_contacts_delete_contact (switched off) deletes a contact; the API cannot restore it, so name the contact and get a clear yes first.

Quotas: Google limits reads, searches and writes per minute per user and per project. Over the limit it answers 429 RESOURCE_EXHAUSTED: wait a minute and retry, and prefer one search over many single reads.

Common errors

• 401: the authorization expired or was revoked (always after 7 days while the consent screen is in Testing). Click Authorize with Provider again.
• 403 PERMISSION_DENIED: the scope does not allow the call (a read-only or missing "Other contacts" scope). 403 "People API has not been used in project": enable the Google People API in the Cloud project.
• 404: the id is wrong or the contact was deleted; pass only the part after people/.
• 400 failedPrecondition on update: the etag is stale; read the contact again and retry. 400 Invalid personFields: a field name is misspelled (they are camelCase: emailAddresses, phoneNumbers). 400 on create: more than one name, note or birthday.

Out of scope here: the Google Workspace directory, contact photos upload, and merging duplicates.