Skip to main content

​
At a glance

  • Availability: Experimental (how to enable).
  • Auth: OAuth 2.0.
  • Connection: A user authorizes the connection in the provider’s consent screen.
  • Scopes: https://www.googleapis.com/auth/contacts.readonly.
  • Optional scopes: https://www.googleapis.com/auth/contacts.
  • Docs: https://developers.google.com/people/api/rest

​
Credentials

Set these per environment. See Connect an integration. With a managed OAuth app, Connect works without these variables; set them to use your own OAuth app instead.
VariableRequiredDescription
GOOGLE_CLIENT_IDYesGoogle OAuth Client ID Docs.
GOOGLE_CLIENT_SECRETYesGoogle OAuth Client Secret Docs.

​
Setup

  1. Create or reuse a Google Cloud project: Go to https://console.cloud.google.com and create a project, or reuse the project that already hosts your shared Google OAuth app. Any free Google account works for testing - add a few contacts at https://contacts.google.com to have data to query.
  2. Enable the People API: Open https://console.cloud.google.com/apis/library/people.googleapis.com, select your project, and click Enable. Google Contacts data is served by the People API.
  3. Configure the OAuth consent screen and client: Under APIs & Services > Credentials, create (or reuse) an OAuth 2.0 Client ID of type Web application and add your app’s redirect URI ending in /api/auth/google-contacts/callback. The same Google OAuth client can be shared across all Google connectors.
  4. Set environment variables: Set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from the OAuth client you created. These are shared with other Google integrations.
  • The default scope is read-only (contacts.readonly); creating or updating contacts requires granting the optional https://www.googleapis.com/auth/contacts scope.
  • Contact resource names look like ‘people/c123’; tools take just the ID portion after ‘people/’ as the personId parameter.
  • Updates are etag-guarded: fetch the contact (including metadata) first and send its etag and metadata.sources back, plus an updatePersonFields mask naming the changed fields.
  • Search uses a prefix-match cache; send a warmup search with an empty query before the real query for fresh results.
Provider API reference: https://developers.google.com/people/api/rest

​
Tools

ToolAccessDescription
List ContactsReadList the authenticated user’s contacts (connections) with the requested person fields
Search ContactsReadSearch the user’s contacts by prefix match on names, nicknames, email addresses, and phone numbers. For best results send a warmup request with an empty query first, then search.
Get ContactReadGet a single contact by person ID, including the etag needed for updates
List Contact GroupsReadList the user’s contact groups (labels), including system groups and member counts, e.g. to organize or filter contacts
Create ContactWriteCreate a new contact in the user’s Google Contacts (requires the full contacts scope)
Update ContactWriteUpdate an existing contact (requires the full contacts scope). You must pass updatePersonFields naming the fields you are changing, and the body must include the contact’s current etag (fetch it with Get Contact including metadata first); a stale etag fails with a 400 failedPrecondition error.

​
Example prompts

  • Search my Google Contacts for a person and show their email address and phone number.
  • Create a new contact in my Google Contacts with name, email, and phone number.
  • Find a contact and update their email address or phone number in Google Contacts.