> This page is for Agent Handler.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.merge.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.merge.dev/_mcp/server.

# Google Calendar

**Authentication:** OAuth. See [Magic Link](/merge-agent-handler/features/magic-link) for the runtime auth flow, or [Application credentials](/merge-agent-handler/admin-setup/add-oauth-credentials) to bring your own OAuth app.

## Sample use cases

* Find a 30-minute slot tomorrow when I, Anna, and Devon are all free.
* Cancel my 2pm and notify the attendees with a rescheduling link.
* List my meetings this week and flag any without an agenda in the description.

## Available Tools

#### list\_acl\_rules

List all access control rules for a calendar. Returns permissions for each user/group including role and scope. Supports pagination and incremental sync.

#### get\_acl\_rule

Retrieve details of a specific ACL rule by ID. Returns role and scope. Rule ID format: 'user:[email@example.com](mailto:email@example.com)' or 'group:[group@example.com](mailto:group@example.com)'.

#### create\_acl\_rule

Grant access to a calendar by creating an ACL rule. Share with users, groups, domains, or make public. Specify role and scope type.

#### update\_acl\_rule

Completely replace an ACL rule. For partial updates, use patch\_acl\_rule instead.

#### patch\_acl\_rule

Partially update an ACL rule. Only provided fields are modified. Safer than update\_acl\_rule for simple permission changes.

#### delete\_acl\_rule

Permanently delete an ACL rule, removing user/group access. Cannot be undone.

#### watch\_acl\_rules

Set up push notifications for ACL rule changes. Requires publicly accessible HTTPS endpoint. Returns channel ID and resource ID to stop the watch later.

#### get\_calendar

Retrieve complete metadata for a calendar including title, description, timezone, and location.

#### create\_calendar

Create a new secondary calendar with custom title, description, timezone, and location.

#### update\_calendar

Update calendar metadata (title, description, timezone, location). Owner only. For user-specific settings like color/visibility, use update\_calendar\_in\_list.

#### delete\_calendar

Permanently delete a secondary calendar and all events. Cannot be undone. Cannot delete primary calendar. For temporary removal, use remove\_calendar\_from\_list.

#### clear\_calendar

Permanently delete ALL events from a calendar without deleting the calendar itself. Cannot be undone. Calendar structure and sharing remain intact.

#### list\_calendar\_list

List all calendars in user's calendar list with settings and permissions. Includes primary, owned, and subscribed calendars. Supports pagination.

#### get\_calendar\_from\_list

Retrieve user-specific settings for a calendar including custom color, display name, notifications, and visibility.

#### add\_calendar\_to\_list

Subscribe to an existing calendar by adding it to user's calendar list. Set custom color, display name, visibility, and notification preferences.

#### update\_calendar\_in\_list

Update user-specific calendar settings including color, visibility, and notifications. Changes only affect this user.

#### patch\_calendar\_in\_list

Partially update user-specific calendar settings. Only provided fields are modified.

#### remove\_calendar\_from\_list

Unsubscribe from a calendar by removing it from user's list. Calendar itself is not deleted.

#### watch\_calendar\_list

Set up push notifications for calendar list changes. Requires publicly accessible HTTPS endpoint. Returns channel ID and resource ID to stop the watch later.

#### list\_events

List events from a Google Calendar with filtering, search, and pagination. Supports time ranges, event types, recurring event expansion, and incremental sync.

#### get\_event

Retrieve complete details of a specific event by ID including all metadata, attendees, recurrence rules, reminders, and conference data.

#### create\_event

Create a new event with title, location, times, attendees, reminders, recurrence, and conference data.

#### update\_event

Update all fields of an existing event. CRITICAL: start/end times must use identical format (both 'date' OR both 'dateTime'). For partial updates, use patch\_event instead.

#### patch\_event

Partially update specific fields of an event without replacing the entire event. Only provided fields are modified. Safer than update\_event for simple changes.

#### import\_event

Import an event without sending notifications. Useful for bulk imports, migrations, or adding historical events. Preserves original event IDs and timestamps.

#### quick\_add\_event

Create an event using natural language text (e.g., 'Lunch with John tomorrow at 12pm'). Google's AI parses dates, times, and details automatically.

#### watch\_events

Set up push notifications for event changes. Requires publicly accessible HTTPS endpoint. Returns channel ID and resource ID to stop the watch later.

#### get\_event\_instances

Retrieve all instances of a recurring event within a time range. Expands recurring events into actual occurrences with specific dates and times.

#### stop\_watch\_channel

Stop an active push notification channel. Requires channel ID and resource ID from watch creation. Cannot be restarted once stopped.

#### list\_user\_settings

List all user settings and preferences including timezone, date format, time format, and week start day.

#### get\_user\_setting

Retrieve a specific user setting by ID (e.g., 'timezone', 'timeFormat', 'weekStart', 'locale').

#### get\_colors

Retrieve available color palette for calendars and events with color IDs mapped to hex codes.

#### query\_freebusy

Query free/busy availability for multiple calendars within a time range. Returns busy periods for scheduling meetings and finding available time slots.

#### watch\_user\_settings

Set up push notifications for user settings changes. Requires publicly accessible HTTPS endpoint. Returns channel ID and resource ID to stop the watch later.