MCP Tools Reference: calendarmcp.googleapis.com

Tool: create_event

Creates an event on the given calendar.

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

Input Schema

Request message for CreateEvent.

CreateEventRequest

JSON representation 
{
  "summary": string,
  "startTime": string,
  "endTime": string,
  "attendeeEmails": [
    string
  ],
  "attendees": [
    {
      object (Attendee)
    }
  ],
  "recurrenceData": [
    string
  ],
  "overrideReminders": [
    {
      object (Reminder)
    }
  ],
  "attachments": [
    {
      object (Attachment)
    }
  ],

  "calendarId": string

  "description": string

  "location": string

  "allDay": boolean

  "timeZone": string

  "notificationLevel": enum (NotificationLevel)

  "addGoogleMeetUrl": boolean

  "visibility": string

  "colorId": string

  "googleMeetUrl": string

  "guestPermissions": {
    object (GuestPermissions)
  }

  "availability": enum (Availability)

  "eventType": enum (EventType)

  "workingLocationProperties": {
    object (WorkingLocationProperties)
  }
}
Fields
summary

string

Required. Title.
startTime

string

Required. Start time (ISO 8601, for example '2026-04-30T10:00:00Z').
endTime

string

Required. End time (ISO 8601, for example '2026-04-30T11:00:00Z').
attendeeEmails[]
(deprecated)

string

Optional. Deprecated: use attendees instead.
attendees[]

object (Attendee)

Optional. Attendees of the event. For events that are created on the user's primary calendar with at least one other attendee, the current user will automatically be added as an attendee if not already included.
recurrenceData[]

string

Optional. Recurrence rules as RRULE, RDATE, or EXDATE strings (per RFC 5545).
overrideReminders[]

object (Reminder)

Optional. Reminders override calendar defaults.
attachments[]

object (Attachment)

Optional. File attachments.

Union field _calendar_id.

_calendar_id can be only one of the following:
calendarId

string

Optional. ID of the calendar to create the event on. Email address - can be resolved using list_calendars. Default: primary calendar.

Union field _description.

_description can be only one of the following:
description

string

Optional. Description. Can contain HTML.

Union field _location.

_location can be only one of the following:
location

string

Optional. Location.

Union field _all_day.

_all_day can be only one of the following:
allDay

boolean

Optional. Whether the event spans the entire day. If true, start/end times are treated as midnight.

Union field _time_zone.

_time_zone can be only one of the following:
timeZone

string

Optional. IANA Time Zone Database name (for example, America/Los_Angeles). Default: the user's primary time zone. Overrides offsets in start_time and end_time.

Union field _notification_level.

_notification_level can be only one of the following:
notificationLevel

enum (NotificationLevel)

Optional. Which email notification should be sent for this event update.

Union field _add_google_meet_url.

_add_google_meet_url can be only one of the following:
addGoogleMeetUrl

boolean

Optional. Create and add a Google Meet URL. Default: false.

Union field _visibility.

_visibility can be only one of the following:
visibility

string

Optional. Visibility of the event. Possible values are:

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

Union field _color_id.

_color_id can be only one of the following:
colorId

string

Optional. The color of the event. For a list of color IDs, refer to the documentation of the Event resource.

Union field _google_meet_url.

_google_meet_url can be only one of the following:
googleMeetUrl

string

Optional. Specific Google Meet URL or meeting ID. Overrides add_google_meet_url.

Union field _guest_permissions.

_guest_permissions can be only one of the following:
guestPermissions

object (GuestPermissions)

Optional. Guest permissions.

Union field _availability.

_availability can be only one of the following:
availability

enum (Availability)

Optional. Availability setting.

Union field _event_type.

_event_type can be only one of the following:
eventType

enum (EventType)

Optional. Type of the event.

Union field _working_location_properties.

_working_location_properties can be only one of the following:
workingLocationProperties

object (WorkingLocationProperties)

Optional. Working location properties (if eventType is WORKING_LOCATION).

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.

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.

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.

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.

NotificationLevel

Email notification level for updates.

Enums
NOTIFICATION_LEVEL_UNSPECIFIED Default. Treated as ALL.
NONE No notifications.
EXTERNAL_ONLY External attendees only.
ALL All attendees.

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.

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.

Output Schema

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