MCP Tools Reference: calendarmcp.googleapis.com

Tool: list_events

Returns events on the given calendar matching all specified constraints. Time constraints should not be specified unless requested by the user. For open-ended keyword or topic-based searches on the primary calendar, the search_events tool must be used instead.

The following sample demonstrate how to use curl to invoke the list_events MCP tool.

Curl Request 
curl --location 'https://calendarmcp.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "list_events",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

ListEventsRequest

JSON representation 
{
  "eventTypeFilter": [
    string
  ],
  "eventType": [
    enum (EventType)
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}
Fields
eventTypeFilter[]
(deprecated)

string

Optional. Deprecated: use event_type instead.
eventType[]

enum (EventType)

Optional. The event types to return. If empty, only the following event types are returned: DEFAULT, OUT_OF_OFFICE, FOCUS_TIME, FROM_GMAIL

Union field _calendar_id.

_calendar_id can be only one of the following:
calendarId

string

Optional. ID of the calendar containing the events. Email address - can be resolved using list_calendars. Default: primary calendar.

Union field _page_size.

_page_size can be only one of the following:
pageSize

integer

Optional. Max events per page (default 100, max 250). Recommended: 10.

Union field _page_token.

_page_token can be only one of the following:
pageToken

string

Optional. Next page token. Use the value from the previous page's nextPageToken.

Union field _start_time.

_start_time can be only one of the following:
startTime

string

Optional. The lower bound of a time range. Must only be set when a specific timeframe is requested by the user. Must be an ISO 8601 timestamp less than end_time.

Union field _end_time.

_end_time can be only one of the following:
endTime

string

Optional. The upper bound of a time range. Must only be set when a specific timeframe or a time in the past is requested by the user. Must be an ISO 8601 timestamp greater than start_time.

Union field _time_zone.

_time_zone can be only one of the following:
timeZone

string

Optional. Time zone (IANA ID, for example Europe/Zurich) used to resolve timezone-less dates. Default: calendar's timezone.

Union field _order_by.

_order_by can be only one of the following:
orderBy

string

Optional. The order in which events should be returned. Possible values are:

  • default - Unspecified, but deterministic ordering (default).
  • startTime - Order by start time ascending.
  • startTimeDesc - Order by start time descending.
  • lastModified - Order by last modification time ascending.

Union field _full_text.

_full_text can be only one of the following:
fullText

string

Optional. Free-form case-insensitive search matching title, description, location, or attendees. Matches events containing all query terms verbatim (AND search).

EventType

Event type. Immutable after creation.

Enums
EVENT_TYPE_UNSPECIFIED Treated as DEFAULT.
DEFAULT Regular event. Default value.
OUT_OF_OFFICE Out-of-office event.
FOCUS_TIME Focus-time event.
WORKING_LOCATION Working location event.
BIRTHDAY Special all-day event with an annual recurrence.
FROM_GMAIL Event from Gmail. This type of event cannot be created.

Output Schema

ListEventsResponse

JSON representation 
{
  "summary": string,
  "description": string,
  "updated": string,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      object (Reminder)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],

  "nextPageToken": string
}
Fields
summary

string

Title of the calendar.
description

string

Description of the calendar.
updated

string

Last update time (ISO 8601) of the calendar.
timeZone

string

Time zone of the calendar.
accessRole

string

Output only. User's access role for the calendar. Possible values are:

  • none - No access.
  • freeBusyReader - Read access to free/busy information.
  • reader - Read access to the calendar. Private events will appear, but event details are hidden.
  • writer - Read and write access. Private events will appear, and event details are visible.
  • owner - Manager access, including the ability to modify sharing settings of the calendar.
Important: The owner role is different from the calendar's data owner. A calendar has a single data owner, but can have multiple users with owner role.
defaultReminders[]

object (Reminder)

Default reminders for events on the calendar.
events[]

object (Event)

List of events.

Union field _next_page_token.

_next_page_token can be only one of the following:
nextPageToken

string

Next page token. Omitted if no next page exists.

Reminder

JSON representation 
{

  "method": string

  "minutes": integer
}
Fields

Union field _method.

_method can be only one of the following:
method

string

Required. Delivery method. Possible values are:

  • email - Reminders are sent via email.
  • popup - Reminders are sent via a UI popup.

Union field _minutes.

_minutes can be only one of the following:
minutes

integer

Required. Minutes in advance that the reminder is triggered.

Event

JSON representation 
{
  "id": string,
  "status": string,
  "htmlLink": string,
  "created": string,
  "updated": string,
  "summary": string,
  "description": string,
  "location": string,
  "creator": {
    object (Principal)
  },
  "organizer": {
    object (Principal)
  },
  "start": {
    object (DateOrDateTime)
  },
  "end": {
    object (DateOrDateTime)
  },
  "recurrence": [
    string
  ],
  "recurringEventId": string,
  "originalStartTime": {
    object (DateOrDateTime)
  },
  "transparency": string,
  "visibility": string,
  "attendees": [
    {
      object (Attendee)
    }
  ],
  "conferenceUrl": string,
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ],
  "attachments": [
    {
      object (Attachment)
    }
  ],
  "guestPermissions": {
    object (GuestPermissions)
  },
  "eventType": enum (EventType),
  "workingLocationProperties": {
    object (WorkingLocationProperties)
  },
  "availability": enum (Availability)
}
Fields
id

string

Unique identifier.
status

string

Optional. Status. Possible values are:

  • confirmed - Event is confirmed (default).
  • tentative - Event is tentatively confirmed.
  • cancelled - Event is cancelled or deleted.
htmlLink

string

Output only. An absolute link to this event in the Google Calendar Web UI.
created

string

Output only. Creation time (ISO 8601).
updated

string

Output only. Last modification time (ISO 8601).
summary

string

Title.
description

string

Optional. Description. Can contain HTML.
location

string

Optional. Location.
creator

object (Principal)

Output only. Creator.
organizer

object (Principal)

Output only. Organizer. Also listed in attendees if attending.
start

object (DateOrDateTime)

Start time (inclusive). For recurring events the first instance is used..
end

object (DateOrDateTime)

End time (exclusive). For recurring events the first instance is used.
recurrence[]

string

Recurrence rules as RRULE, EXRULE, RDATE, or EXDATE strings (per RFC 5545). Omitted for single events. Start/end times must be set in the start/end fields.
recurringEventId

string

Parent recurring event ID for instances of recurring events.
originalStartTime

object (DateOrDateTime)

Original start time of recurring instances. This is the time at which this instance would start according to the recurrence data.
transparency
(deprecated)

string

Optional. Deprecated: use availability instead.
visibility

string

Optional. Visibility of the event. Possible values are:

  • default - Uses the default visibility for events on the calendar. This is the default value.
  • public - Event details are visible to all readers of the calendar.
  • private - Only event attendees may view event details.

attendees[]

object (Attendee)

Attendees.
conferenceUrl

string

Video conference link.
colorId

string

The color of the event. Only affects your own calendar view. This is an ID referring to an entry in the calendar's color palette (string '1'-'11'):

  • 1: Lavender
  • 2: Sage
  • 3: Grape
  • 4: Flamingo
  • 5: Banana
  • 6: Tangerine
  • 7: Peacock
  • 8: Graphite
  • 9: Blueberry
  • 10: Basil
  • 11: Tomato.

overrideReminders[]

object (Reminder)

Reminders. Falls back to calendar defaults if unset.
attachments[]

object (Attachment)

File attachments.
guestPermissions

object (GuestPermissions)

Guest permissions.
eventType

enum (EventType)

Event type.
workingLocationProperties

object (WorkingLocationProperties)

Working location properties. Populated only when event_type is WORKING_LOCATION.
availability

enum (Availability)

Optional. Availability setting.

Principal

JSON representation 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
Fields
email

string

Email.
displayName

string

Name.
self

boolean

Output only. Whether this principal corresponds to the calendar on which this copy of the event appears. Default: false.

DateOrDateTime

JSON representation 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
Fields
date

string

ISO 8601 date at midnight UTC (for example, '2019-11-20T00:00:00Z').
dateTime

string

ISO 8601 timestamp (for example, '2019-11-20T08:19:06-07:00').
timeZone

string

TZDB timezone name.

Attendee

JSON representation 
{

  "id": string

  "email": string

  "displayName": string

  "organizer": boolean

  "self": boolean

  "resource": boolean

  "optionalAttendee": boolean

  "responseStatus": string

  "comment": string

  "additionalGuests": integer
}
Fields

Union field _id.

_id can be only one of the following:
id

string

Output only. Profile ID.

Union field _email.

_email can be only one of the following:
email

string

Required. Attendee's email address.

Union field _display_name.

_display_name can be only one of the following:
displayName

string

Optional. Name.

Union field _organizer.

_organizer can be only one of the following:
organizer

boolean

Output only. Whether attendee is the organizer. Default: false.

Union field _self.

_self can be only one of the following:
self

boolean

Output only. Whether this entry represents the calendar on which this copy of the event appears. Default: false.

Union field _resource.

_resource can be only one of the following:
resource

boolean

Optional. Whether attendee is a resource (for example, room). Immutable, can only be set when the attendee is initially added. Default: false.

Union field _optional_attendee.

_optional_attendee can be only one of the following:
optionalAttendee

boolean

Optional. Whether attendee is optional. Default: false.

Union field _response_status.

_response_status can be only one of the following:
responseStatus

string

Optional. Response status. Possible values are:

  • needsAction - Attendee has not responded to the invitation (recommended for new events).
  • declined - Attendee has declined the invitation.
  • tentative - Attendee has tentatively accepted the invitation.
  • accepted - Attendee has accepted the invitation.

Union field _comment.

_comment can be only one of the following:
comment

string

Output only. Response comment.

Union field _additional_guests.

_additional_guests can be only one of the following:
additionalGuests

integer

Optional. Number of additional guests. Default: 0.

Attachment

JSON representation 
{

  "fileUrl": string

  "title": string
}
Fields

Union field _file_url.

_file_url can be only one of the following:
fileUrl

string

Required. URL link to the attachment.

Union field _title.

_title can be only one of the following:
title

string

Optional. Attachment title.

GuestPermissions

JSON representation 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
Fields

Union field _guests_can_invite_others.

_guests_can_invite_others can be only one of the following:
guestsCanInviteOthers

boolean

Optional. Whether guests can invite others.

Union field _guests_can_modify.

_guests_can_modify can be only one of the following:
guestsCanModify

boolean

Optional. Whether guests can modify the event.

Union field _guests_can_see_guests.

_guests_can_see_guests can be only one of the following:
guestsCanSeeGuests

boolean

Optional. Whether guests can see other guests.

WorkingLocationProperties

JSON representation 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
Fields

Union field _type.

_type can be only one of the following:
type

enum (WorkingLocationType)

Optional. Working location type.

Union field _custom_location_label.

_custom_location_label can be only one of the following:
customLocationLabel

string

Optional. The label for a custom location. Required if type is CUSTOM_LOCATION.

EventType

Event type. Immutable after creation.

Enums
EVENT_TYPE_UNSPECIFIED Treated as DEFAULT.
DEFAULT Regular event. Default value.
OUT_OF_OFFICE Out-of-office event.
FOCUS_TIME Focus-time event.
WORKING_LOCATION Working location event.
BIRTHDAY Special all-day event with an annual recurrence.
FROM_GMAIL Event from Gmail. This type of event cannot be created.

WorkingLocationType

Type of working location.

Enums
WORKING_LOCATION_TYPE_UNSPECIFIED Unspecified working location type. Will be treated as HOME_OFFICE.
HOME_OFFICE Home office.
CUSTOM_LOCATION Custom location.

Availability

Availability setting for an event.

Enums
AVAILABILITY_UNSPECIFIED Default. Treated as BUSY.
AVAILABILITY_BUSY Blocks time on calendar.
AVAILABILITY_FREE Does not block time.

Tool Annotations

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌