# Google Calendar — how to use (mcp.ai)

Google Calendar em linguagem natural: liste, crie, atualize e remova eventos, cheque disponibilidade e convide participantes. A plataforma fornece a aplicação OAuth, você só clica em Conectar e escolhe sua conta Google. Várias contas podem ser conectadas no mesmo MCP.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_googlecalendar?ms=1781045220000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `googlecalendar_calendar_list_insert`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/googlecalendar`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/googlecalendar/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/googlecalendar/calendar/list/insert` — Inserts an existing calendar into the user's calendar list.
  - body: { id: string, hidden?: boolean, color_id?: string, selected?: boolean, background_color?: string, color_rgb_format?: boolean, foreground_color?: string, summary_override?: string, default_reminders?: object[], notification_settings?: object }
- `POST https://api.mcp.ai/api/googlecalendar/calendar/list/update` — Updates an existing entry on the user\'s calendar list.
  - body: { hidden?: boolean, colorId?: string, selected?: boolean, calendar_id: string, colorRgbFormat?: boolean, backgroundColor?: string, foregroundColor?: string, summaryOverride?: string, defaultReminders?: object[], notificationSettings?: object }
- `POST https://api.mcp.ai/api/googlecalendar/calendars/delete` — Deletes a secondary calendar. use calendars.clear for clearing all events on primary calendars.
  - body: { calendar_id: string }
- `POST https://api.mcp.ai/api/googlecalendar/calendars/update` — Updates metadata for a calendar.
  - body: { summary: string, location?: string, timeZone?: string, calendarId: string, description?: string }
- `POST https://api.mcp.ai/api/googlecalendar/clear/calendar` — Clears a primary calendar. this operation deletes all events associated with the primary calendar of an account.
  - body: { calendar_id: string }
- `POST https://api.mcp.ai/api/googlecalendar/create/event` — Creates an event on a google calendar, needing rfc3339 utc start/end times (end after start) and write access to the calendar. by default, adds the organizer as an attendee unless exclude organizer is
  - body: { summary?: string, location?: string, timezone?: string, attendees?: string[], eventType?: string, recurrence?: string[], visibility?: string, calendar_id?: string, description?: string, send_updates?: boolean, transparency?: string, start_datetime: string, exclude_organizer?: boolean, guests_can_modify?: boolean, create_meeting_room?: boolean, event_duration_hour?: integer, guestsCanInviteOthers?: boolean, event_duration_minutes?: integer, guestsCanSeeOtherGuests?: boolean }
- `POST https://api.mcp.ai/api/googlecalendar/delete/event` — Deletes a specified event by `event id` from a google calendar (`calendar id`); this action is idempotent and raises a 404 error if the event is not found.
  - body: { event_id: string, calendar_id?: string }
- `POST https://api.mcp.ai/api/googlecalendar/duplicate/calendar` — Creates a new, empty google calendar with the specified title (summary).
  - body: { summary?: string }
- `POST https://api.mcp.ai/api/googlecalendar/events/instances` — Returns instances of the specified recurring event.
  - body: { eventId: string, timeMax?: string, timeMin?: string, timeZone?: string, pageToken?: string, calendarId: string, maxResults?: integer, showDeleted?: boolean, maxAttendees?: integer, originalStart?: string }
- `POST https://api.mcp.ai/api/googlecalendar/events/list` — Returns events on the specified calendar.
  - body: { q?: string, iCalUID?: string, orderBy?: string, timeMax?: string, timeMin?: string, timeZone?: string, pageToken?: string, syncToken?: string, calendarId: string, eventTypes?: string, maxResults?: integer, updatedMin?: string, showDeleted?: boolean, maxAttendees?: integer, singleEvents?: boolean, alwaysIncludeEmail?: boolean, showHiddenInvitations?: boolean, sharedExtendedProperty?: string, privateExtendedProperty?: string }
- `POST https://api.mcp.ai/api/googlecalendar/events/move` — Moves an event to another calendar, i.e., changes an event's organizer.
  - body: { event_id: string, calendar_id: string, destination: string, send_updates?: string }
- `POST https://api.mcp.ai/api/googlecalendar/events/watch` — Watch for changes to events resources.
  - body: { id: string, type?: string, token?: string, params?: object, address: string, payload?: boolean, calendarId: string }
- `POST https://api.mcp.ai/api/googlecalendar/find/event` — Finds events in a specified google calendar using text query, time ranges (event start/end, last modification), and event types; ensure `timemin` is not chronologically after `timemax` if both are pro
  - body: { query?: string, timeMax?: string, timeMin?: string, order_by?: string, page_token?: string, calendar_id?: string, event_types?: string[], max_results?: integer, updated_min?: string, show_deleted?: boolean, single_events?: boolean }
- `POST https://api.mcp.ai/api/googlecalendar/find/free/slots` — Finds free/busy time slots in google calendars for specified calendars within a defined time range (defaults to the current day utc if `time min`/`time max` are omitted), enhancing busy intervals with
  - body: { items?: string[], time_max?: string, time_min?: string, timezone?: string, group_expansion_max?: integer, calendar_expansion_max?: integer }
- `POST https://api.mcp.ai/api/googlecalendar/free/busy/query` — Returns free/busy information for a set of calendars.
  - body: { items: object[], timeMax: string, timeMin: string, timeZone?: string, groupExpansionMax?: integer, calendarExpansionMax?: integer }
- `POST https://api.mcp.ai/api/googlecalendar/get/calendar` — Retrieves a specific google calendar, identified by `calendar id`, to which the authenticated user has access.
  - body: { calendar_id?: string }
- `POST https://api.mcp.ai/api/googlecalendar/get/current/date/time` — Gets the current date and time, allowing for a specific timezone offset.
  - body: { timezone?: number }
- `POST https://api.mcp.ai/api/googlecalendar/list/acl/rules` — Retrieves the list of access control rules (acls) for a specified calendar, providing the necessary 'rule id' values required for updating specific acl rules.
  - body: { page_token?: string, sync_token?: string, calendar_id: string, max_results?: integer, show_deleted?: boolean }
- `POST https://api.mcp.ai/api/googlecalendar/list/calendars` — Retrieves calendars from the user's google calendar list, with options for pagination and filtering.
  - body: { page_token?: string, sync_token?: string, max_results?: integer, show_hidden?: boolean, show_deleted?: boolean, min_access_role?: string }
- `POST https://api.mcp.ai/api/googlecalendar/patch/calendar` — Partially updates (patches) an existing google calendar, modifying only the fields provided; `summary` is mandatory and cannot be an empty string, and an empty string for `description` or `location` c
  - body: { summary: string, location?: string, timezone?: string, calendar_id: string, description?: string }
- `POST https://api.mcp.ai/api/googlecalendar/patch/event` — Updates specified fields of an existing event in a google calendar using patch semantics (array fields like `attendees` are fully replaced if provided); ensure the `calendar id` and `event id` are val
  - body: { summary?: string, end_time?: string, event_id: string, location?: string, timezone?: string, attendees?: string[], start_time?: string, calendar_id: string, description?: string, send_updates?: string, max_attendees?: integer, rsvp_response?: string, supports_attachments?: boolean, conference_data_version?: integer }
- `POST https://api.mcp.ai/api/googlecalendar/quick/add` — Parses natural language text to quickly create a basic google calendar event with its title, date, and time, suitable for simple scheduling; does not support direct attendee addition or recurring even
  - body: { text?: string, calendar_id?: string, send_updates?: string }
- `POST https://api.mcp.ai/api/googlecalendar/remove/attendee` — Removes an attendee from a specified event in a google calendar; the calendar and event must exist.
  - body: { event_id: string, calendar_id?: string, attendee_email: string }
- `POST https://api.mcp.ai/api/googlecalendar/settings/list` — Returns all user settings for the authenticated user.
  - body: { pageToken?: string, syncToken?: string, maxResults?: integer }
- `POST https://api.mcp.ai/api/googlecalendar/settings/watch` — Watch for changes to settings resources.
  - body: { id: string, type: string, token?: string, params?: object, address: string }
- `POST https://api.mcp.ai/api/googlecalendar/sync/events` — Synchronizes google calendar events, performing a full sync if no `sync token` is provided or if a 410 gone error (due to an expired token) necessitates it, otherwise performs an incremental sync for 
  - body: { pageToken?: string, sync_token?: string, calendar_id?: string, event_types?: string[], max_results?: integer, single_events?: boolean }
- `POST https://api.mcp.ai/api/googlecalendar/update/acl/rule` — Updates an access control rule for the specified calendar.
  - body: { role: string, rule_id: string, calendar_id: string, send_notifications?: boolean }
- `POST https://api.mcp.ai/api/googlecalendar/update/event` — Updates an existing event by `event id` in a google calendar; this is a full put replacement, so provide all desired fields as unspecified ones may be cleared or reset.
  - body: { summary?: string, event_id: string, location?: string, timezone?: string, attendees?: string[], eventType?: string, recurrence?: string[], visibility?: string, calendar_id?: string, description?: string, send_updates?: boolean, transparency?: string, start_datetime: string, guests_can_modify?: boolean, create_meeting_room?: boolean, event_duration_hour?: integer, guestsCanInviteOthers?: boolean, event_duration_minutes?: integer, guestsCanSeeOtherGuests?: boolean }

## Example prompts
- "O que tenho na agenda amanhã?"
- "Crie uma reunião 'Review' quinta às 15h por 1h e convide joao@ex.com"
- "Acho um horário livre de 30min na próxima semana à tarde"

## More
- Page: https://mcp.ai/googlecalendar
- Agent spec (llms.txt): https://mcp.ai/googlecalendar/llms.txt
- Postman collection: https://mcp.ai/googlecalendar/postman.json