Google Contacts Connector

Use this page when you need the Google-side setup details for the Google Contacts connector. For shared connector behavior, start with Connectors Overview and Provider Auth And Setup.

Runtime Shape

• Implemented modes: fixed live
• Auth binding: Better Auth generic OAuth provider id google
• Callback URI examples:
  • http://localhost:3001/api/auth/oauth2/callback/google
  • https://auth.example.com/api/auth/oauth2/callback/google
• Setup console URL:
  • Google Cloud Console credentials
  • Google People API enablement
• Required connector scopes:
  • https://www.googleapis.com/auth/contacts.readonly

Provider-Specific Gotchas

• Google Contacts is live-only for storage in this repo. There is no contact sync, Meltano tap, indexed mode, or embeddings path.
• The OAuth scope is not enough by itself: the Google Cloud project behind the OAuth client must have People API enabled. A linked account with contacts.readonly still fails closed as not configured when Google returns the documented “API has not been used or is disabled” response.
• The runtime uses Google People API people.searchContacts for focused saved-contact lookup. It sends the documented empty-query warmup request before focused search, uses an explicit readMask, and caps pageSize at 30.
• Broad saved-contact list prompts use Google People API people.connections.list with CONTACT source, explicit personFields, bounded pageSize, and provider sort semantics.
• Google People API contact search covers CONTACT-source saved contacts with prefix phrase matching. Do not treat it as Google Workspace Directory search, and do not add directory scopes unless product explicitly expands the connector scope.
• Google Contacts, Gmail, and Google Drive share the same connector auth binding. Reauthorization under an existing linked google account requests the full scope set needed by sibling Google connectors under that account.
• Contact grounding must label Google results as saved-contact and keep provider ids out of user-facing answer text unless the user explicitly asks for identifiers.

Canonical Sources

• packages/domain/src/connectors/connectorRegistry.ts
• apps/auth/src/genericOAuthProviders.ts
• apps/api/src/mastra/tools/googleContactsLiveQuery.ts
• apps/api/src/connectors/liveAccessContactContracts.ts
• docs/features/connectors/spec.md
• docs/features/live-query/spec.md

Official Docs

• Google People API people.searchContacts
• Google People API people.connections.list
• Google People API contacts guide