MCP Tools Reference: calendarmcp.googleapis.com

Tool: search_events

Searches events on the user's primary calendar using semantic search.

The following sample demonstrate how to use curl to invoke the search_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": "search_events",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request message for SearchEvents.

SearchEventsRequest

JSON representation 
{
  "query": string,

  "pageSize": integer

  "pageToken": string
}
Fields
query

string

Required. Query string to search for events (case-insensitive).

Union field _page_size.

_page_size can be only one of the following:
pageSize

integer

Optional. Maximum number of entries returned on one result page.

Union field _page_token.

_page_token can be only one of the following:
pageToken

string

Optional. Token specifying which result page to return.

Output Schema

Response message for SearchEvents.

SearchEventsResponse

JSON representation 
{
  "events": [
    {
      object (Event)
    }
  ],

  "nextPageToken": string
}
Fields
events[]

object (Event)

List of events matching the query.

Union field _next_page_token.

_next_page_token can be only one of the following:
nextPageToken

string

Token used to access the next page of this result.

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.

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.

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: ❌