Google Calendar Connector

Use this page when you need the Google-side setup details for the Google Calendar 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 Calendar API enablement
• Required connector scopes:
  • https://www.googleapis.com/auth/calendar.calendarlist.readonly
  • https://www.googleapis.com/auth/calendar.events.readonly

Provider-Specific Gotchas

• Google Calendar is live-only for storage in this repo. There is no calendar sync, Meltano tap, indexed mode, or embeddings path.
• The OAuth scopes are not enough by themselves: the Google Cloud project behind the OAuth client must have Google Calendar API enabled.
• Calendar discovery uses Google Calendar API CalendarList.list.
• Date-window and upcoming event lookup uses Events.list with timeMin, timeMax, singleEvents=true, and orderBy=startTime.
• Focused event search uses Events.list with q and an optional date window.
• Recently changed event lookup uses updatedMin only. Do not combine syncToken with q, timeMin, timeMax, or orderBy.
• Do not use deprecated alwaysIncludeEmail.
• Private or shared calendars may hide event details based on the user’s access role. Calendar grounding must preserve private/limited-detail source kinds instead of inventing hidden details.
• Google Calendar, 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.

Canonical Sources

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

Official Docs

• Google Calendar API authorization
• Google Calendar API calendarList.list
• Google Calendar API events.list