MCP Tools Reference: calendarmcp.googleapis.com

Tool: suggest_time

Suggests time periods across one or more calendars. To access the primary calendar, add 'primary' in the attendee_emails field.

Use this tool for queries like:

  • When are all of us free for a meeting?
  • Find a 30 minute slot where we are both available.
  • Check if jane.doe@google.com is free on Monday morning.

Example:

suggest_time(
            attendee_emails=['joedoe@gmail.com', 'janedoe@gmail.com'],
            start_time='2024-09-10T00:00:00',
            end_time='2024-09-17T00:00:00',
            duration_minutes=60,
            preferences={
                'start_hour': '09:00',
                'end_hour': '17:00',
                'exclude_weekends': True
            }
        )
        # Returns up to 5 suggested time slots where both users are available for at least one hour between 9:00 AM and 5:00 PM on weekdays from September 10 through September 16, 2024.

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

Input Schema

Request message for SuggestTime.

SuggestTimeRequest

JSON representation 
{
  "attendeeEmails": [
    string
  ],
  "startTime": string,
  "endTime": string,

  "timeZone": string

  "durationMinutes": integer

  "preferences": {
    object (Preferences)
  }
}
Fields
attendeeEmails[]

string

Required. The attendee emails to find free time for.
startTime

string

Required. The start of the interval for the query formatted as per ISO 8601.
endTime

string

Required. The end of the interval for the query formatted as per ISO 8601.

Union field _time_zone.

_time_zone can be only one of the following:
timeZone

string

Optional. Time zone used for the time values. This field accepts IANA Time Zone database names, e.g., America/Los_Angeles. The default is the time zone of the user's primary calendar.

Union field _duration_minutes.

_duration_minutes can be only one of the following:
durationMinutes

integer

Optional. Minimum duration of a free time slot in minutes. The default is 30 minutes.

Union field _preferences.

_preferences can be only one of the following:
preferences

object (Preferences)

The preferences to find suggested time for.

Preferences

JSON representation 
{

  "startHour": string

  "endHour": string

  "excludeWeekends": boolean

  "pageSize": integer
}
Fields

Union field _start_hour.

_start_hour can be only one of the following:
startHour

string

The preferred start hour of day (e.g., 09:00).

Union field _end_hour.

_end_hour can be only one of the following:
endHour

string

The preferred end hour of day (e.g., 17:00).

Union field _exclude_weekends.

_exclude_weekends can be only one of the following:
excludeWeekends

boolean

Whether to exclude weekends.

Union field _page_size.

_page_size can be only one of the following:
pageSize

integer

Maximum number of time slots to return. Default is 5.

Output Schema

Response message for SuggestTime.

SuggestTimeResponse

JSON representation 
{
  "timeSlots": [
    {
      object (TimeSlot)
    }
  ]
}
Fields
timeSlots[]

object (TimeSlot)

List of suggested time slots.

TimeSlot

JSON representation 
{
  "startTime": string,
  "endTime": string,
  "durationMinutes": integer
}
Fields
startTime

string

The start time of the free time slot as an ISO 8601 formatted timestamp.
endTime

string

The end time of the free time slot as an ISO 8601 formatted timestamp.
durationMinutes

integer

The duration of the free time slot in minutes.

Tool Annotations

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