Google Calendar Events
Let an agent schedule on Google Calendar: list calendars, read upcoming events and recurring instances, check free/busy across people, and create or update events with attendees. Based on the Google Calendar API specification.
Connect this API to an AI agent Browse all specs
What you can do with Google Calendar Events via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /users/me/calendarList |
listCalendars | List the calendars in the user's calendar list |
| GET | /calendars/{calendarId}/events |
listEvents | List events in a time window (use singleEvents=true and orderBy=startTime) |
| POST | /calendars/{calendarId}/events |
createEvent | Create an event, optionally inviting attendees |
| GET | /calendars/{calendarId}/events/{eventId} |
getEvent | Get one event with its attendees and status |
| PATCH | /calendars/{calendarId}/events/{eventId} |
updateEvent | Change some fields of an event (time, title, attendees, description) |
| GET | /calendars/{calendarId}/events/{eventId}/instances |
listEventInstances | List the individual occurrences of a recurring event |
| POST | /freeBusy |
queryFreeBusy | Check when calendars are busy in a time range before proposing a slot |
| POST | /calendars/{calendarId}/events/quickAdd |
quickAddEvent | Create an event from a plain-text sentence like 'Lunch with Ana tomorrow 12pm' |
Authentication
googleOAuth
OAuth 2.0
Scopes: https://www.googleapis.com/auth/calendar.readonly https://www.googleapis.com/auth/calendar.events
Google OAuth 2.0 (authorization code flow) on behalf of the signed-in user.
How to get a credential
- In the Google Cloud Console (https://console.cloud.google.com) create or pick a project and enable the Google Calendar API (APIs & Services > Library).
- Configure the OAuth consent screen (Google Auth Platform > Branding / Audience) and add the scopes below under Data Access. While the app is in Testing, add your users as test users.
- Create an OAuth client ID of type Web application and add the VX Agents redirect URI shown in the credential dialog as an authorized redirect URI.
- Paste the client ID and client secret into the VX Agents credential and connect your Google account; request offline access so the token can refresh.
Permissions used
| Scope | Operations |
|---|---|
https://www.googleapis.com/auth/calendar.readonly |
listCalendars, listEvents, getEvent, listEventInstances, queryFreeBusy |
https://www.googleapis.com/auth/calendar.events |
createEvent, quickAddEvent, updateEvent (also allows reading events) |
Common errors
- 401 Unauthorized (
invalid_credentials): the access token expired or was revoked; reconnect the account or refresh the token. - 403 Forbidden:
insufficientPermissions= the token lacks the scope (reconnect with calendar.events for writes);accessNotConfigured= enable the Calendar API in the Cloud project;forbiddenForNonOrganizer= only the organizer can change that field. - 400 Bad Request: usually a time without an offset/timeZone, end before start, or an invalid
timeMin/timeMax. - 404 Not Found: wrong calendarId/eventId or a calendar the user cannot access.
- 429 / 403 rateLimitExceeded: too many requests; back off exponentially and retry.
Store the connected Google account as a VX Agents credential for this spec; never paste tokens into chat.
Usage guide
Setup
- Credential: connect a Google account with OAuth (calendar.readonly to read, calendar.events to create/update).
- Preset
calendarId=primaryfor the user's own calendar. Other calendars use their id from listCalendars (often an email address). - Know the user's time zone (listCalendars returns
timeZonefor each calendar) and use it in every time you send.
Schedule a meeting
- listCalendars once to learn the time zone and which calendars exist.
- queryFreeBusy with
timeMin,timeMax,timeZoneanditems: [{id: "primary"}, {id: "[email protected]"}]to find open slots. Only propose slots that are free for everyone you could check. - listEvents with
timeMin/timeMax,singleEvents=true,orderBy=startTimeto see what is already booked (and to avoid duplicates). - Show the user the proposed event: title, start/end with time zone, attendees, location/description. Wait for confirmation.
- createEvent with
summary,start: {dateTime, timeZone},end: {dateTime, timeZone},attendees: [{email}]andsendUpdates=allif guests should get invitations (noneto stay silent). - To reschedule or edit, getEvent first, confirm the change with the user, then updateEvent (PATCH: send only the fields that change). Changing attendees or time sends updates when
sendUpdates=all.
Other tools
- quickAddEvent with
textcreates an event from a sentence ("Dentist Friday 3pm"); confirm the result with getEvent. - listEventInstances expands one recurring event into occurrences, e.g. to move a single instance.
Good to know
- Times are RFC 3339 with an explicit offset (
2026-10-20T14:00:00+07:00); all-day events usestart.date/end.date(end date is exclusive). - Without
singleEvents=true, recurring events come back once with an RRULE instead of each occurrence. - Lists page with
pageToken/nextPageToken;maxResultsup to 2500 for events. - Creating or changing events with attendees emails real people: always confirm first. Deleting events is intentionally not available.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Google Calendar Events” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.