MCP Tools Reference: calendarmcp.googleapis.com

工具：create_event

在指定日历上创建活动。

以下示例演示了如何使用 curl 调用 create_event MCP 工具。

Curl 请求 
curl --location 'https://calendarmcp.googleapis.com/mcp/v1' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--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
}'

输入架构

针对 CreateEvent 的请求消息。

CreateEventRequest

JSON 表示法 
{
  "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)
  }
}
字段
summary

string

必需。标题。
startTime

string

必需。开始时间（ISO 8601，例如 '2026-04-30T10:00:00Z'）。
endTime

string

必需。结束时间（ISO 8601 格式，例如 '2026-04-30T11:00:00Z'）。
attendeeEmails[]
(deprecated)

string

可选。已弃用：请改用 attendees。
attendees[]

object (Attendee)

可选。活动的参加者。对于在用户的主日历中创建的活动，如果至少还有一位其他参加者，则系统会自动将当前用户添加为参加者（如果尚未添加）。
recurrenceData[]

string

可选。以 RRULE、RDATE 或 EXDATE 字符串（根据 RFC 5545）表示的重复规则。
overrideReminders[]

object (Reminder)

可选。提醒会覆盖日历默认设置。
attachments[]

object (Attachment)

可选。文件附件。

联合字段 _calendar_id。

_calendar_id 只能是下列其中一项：
calendarId

string

可选。要在其中创建活动的日历的 ID。电子邮件地址 - 可使用 list_calendars 进行解析。默认值：主日历。

联合字段 _description。

_description 只能是下列其中一项：
description

string

可选。说明。可以包含 HTML。

联合字段 _location。

_location 只能是下列其中一项：
location

string

可选。位置信息。

联合字段 _all_day。

_all_day 只能是下列其中一项：
allDay

boolean

可选。活动是否持续一整天。如果为 true，则将开始/结束时间视为午夜。

联合字段 _time_zone。

_time_zone 只能是下列其中一项：
timeZone

string

可选。IANA 时区数据库名称（例如 America/Los_Angeles）。默认值：用户的主要时区。替换 start_time 和 end_time 中的偏移量。

联合字段 _notification_level。

_notification_level 只能是下列其中一项：
notificationLevel

enum (NotificationLevel)

可选。应针对此活动更新发送哪种电子邮件通知。

联合字段 _add_google_meet_url。

_add_google_meet_url 只能是下列其中一项：
addGoogleMeetUrl

boolean

可选。创建并添加 Google Meet 网址。默认值：false。

联合字段 _visibility。

_visibility 只能是下列其中一项：
visibility

string

可选。活动的公开范围。可能的值包括：

  • default - 使用日历中活动的默认公开范围。默认值。
  • public - 活动是公开的，日历的所有读者都可以查看活动详情。
  • private - 只有活动参加者可以查看活动详情。

联合字段 _color_id。

_color_id 只能是下列其中一项：
colorId

string

可选。活动的颜色。如需查看颜色 ID 列表，请参阅 Event 资源的文档。

联合字段 _google_meet_url。

_google_meet_url 只能是下列其中一项：
googleMeetUrl

string

可选。特定的 Google Meet 网址或会议 ID。此属性会覆盖 add_google_meet_url。

联合字段 _guest_permissions。

_guest_permissions 只能是下列其中一项：
guestPermissions

object (GuestPermissions)

可选。邀请对象权限。

联合字段 _availability。

_availability 只能是下列其中一项：
availability

enum (Availability)

可选。空闲状态设置。

联合字段 _event_type。

_event_type 只能是下列其中一项：
eventType

enum (EventType)

可选。事件的类型。

联合字段 _working_location_properties。

_working_location_properties 只能是下列其中一项：
workingLocationProperties

object (WorkingLocationProperties)

可选。工作地点属性（如果 eventType 为 WORKING_LOCATION）。

参加者

JSON 表示法 
{

  "id": string

  "email": string

  "displayName": string

  "organizer": boolean

  "self": boolean

  "resource": boolean

  "optionalAttendee": boolean

  "responseStatus": string

  "comment": string

  "additionalGuests": integer
}
字段

联合字段 _id。

_id 只能是下列其中一项：
id

string

仅限输出。个人资料 ID。

联合字段 _email。

_email 只能是下列其中一项：
email

string

必需。参会者的电子邮件地址。

联合字段 _display_name。

_display_name 只能是下列其中一项：
displayName

string

可选。名称。

联合字段 _organizer。

_organizer 只能是下列其中一项：
organizer

boolean

仅限输出。参会者是否为组织者。默认值：false。

联合字段 _self。

_self 只能是下列其中一项：
self

boolean

仅限输出。相应条目是否表示显示相应活动副本的日历。默认值：false。

联合字段 _resource。

_resource 只能是下列其中一项：
resource

boolean

可选。相应出席者是否为资源（例如会议室）。不可变，只能在最初添加参加者时设置。默认值：false。

联合字段 _optional_attendee。

_optional_attendee 只能是下列其中一项：
optionalAttendee

boolean

可选。参会者是否可选。默认值：false。

联合字段 _response_status。

_response_status 只能是下列其中一项：
responseStatus

string

可选。响应状态。可能的值包括：

  • needsAction - 参加者尚未回复邀请（建议用于新活动）。
  • declined - 受邀者已拒绝邀请。
  • tentative - 受邀者已暂时接受邀请。
  • accepted - 受邀者已接受邀请。

联合字段 _comment。

_comment 只能是下列其中一项：
comment

string

仅限输出。回答评论。

联合字段 _additional_guests。

_additional_guests 只能是下列其中一项：
additionalGuests

integer

可选。额外房客人数。默认值：0。

提醒

JSON 表示法 
{

  "method": string

  "minutes": integer
}
字段

联合字段 _method。

_method 只能是下列其中一项：
method

string

必需。投放方式。可能的值包括：

  • email - 系统会通过电子邮件发送提醒。
  • popup - 通过界面弹出式窗口发送提醒。

联合字段 _minutes。

_minutes 只能是下列其中一项：
minutes

integer

必需。提醒触发时间提前的分钟数。

GuestPermissions

JSON 表示法 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
字段

联合字段 _guests_can_invite_others。

_guests_can_invite_others 只能是下列其中一项：
guestsCanInviteOthers

boolean

可选。邀请对象是否可以邀请他人。

联合字段 _guests_can_modify。

_guests_can_modify 只能是下列其中一项：
guestsCanModify

boolean

可选。邀请对象是否可以修改活动。

联合字段 _guests_can_see_guests。

_guests_can_see_guests 只能是下列其中一项：
guestsCanSeeGuests

boolean

可选。邀请对象是否可以查看其他邀请对象。

附件

JSON 表示法 
{

  "fileUrl": string

  "title": string
}
字段

联合字段 _file_url。

_file_url 只能是下列其中一项：
fileUrl

string

必需。附件的网址链接。

联合字段 _title。

_title 只能是下列其中一项：
title

string

可选。附件标题。

WorkingLocationProperties

JSON 表示法 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
字段

联合字段 _type。

_type 只能是下列其中一项：
type

enum (WorkingLocationType)

可选。工作地点类型。

联合字段 _custom_location_label。

_custom_location_label 只能是下列其中一项：
customLocationLabel

string

可选。自定义位置的标签。如果类型为 CUSTOM_LOCATION，则为必填项。

NotificationLevel

电子邮件通知级别（针对更新）。

枚举
NOTIFICATION_LEVEL_UNSPECIFIED 默认值。视为 ALL。
NONE 没有通知。
EXTERNAL_ONLY 仅限外部参会者。
ALL 所有参会者。

可用性

活动的空闲情况设置。

枚举
AVAILABILITY_UNSPECIFIED 默认值。视为 BUSY。
AVAILABILITY_BUSY 在日历上安排时间。
AVAILABILITY_FREE 不屏蔽时间。

EventType

活动类型。一经创建便无法更改。

枚举
EVENT_TYPE_UNSPECIFIED 视为 DEFAULT。
DEFAULT 常规活动。默认值。
OUT_OF_OFFICE “不在办公室”活动。
FOCUS_TIME 专注时间活动。
WORKING_LOCATION 工作地点活动。
BIRTHDAY 每年举办一次的特殊全天活动。
FROM_GMAIL 来自 Gmail 的活动。无法创建此类活动。

WorkingLocationType

工作地点类型。

枚举
WORKING_LOCATION_TYPE_UNSPECIFIED 未指定工作地点类型。将被视为 HOME_OFFICE。
HOME_OFFICE 居家办公。
CUSTOM_LOCATION 自定义位置。

输出架构

活动

JSON 表示法 
{
  "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)
}
字段
id

string

唯一标识符。
status

string

可选。状态。可能的值包括：

  • confirmed - 活动已确认（默认）。
  • tentative - 活动已暂时确认。
  • cancelled - 活动已取消或删除。
htmlLink

string

仅限输出。Google 日历 Web 界面中相应活动的绝对链接。
created

string

仅限输出。创建时间 (ISO 8601)。
updated

string

仅限输出。上次修改时间 (ISO 8601)。
summary

string

标题。
description

string

可选。说明。可以包含 HTML。
location

string

可选。位置信息。
creator

object (Principal)

仅限输出。创作者。
organizer

object (Principal)

仅限输出。组织者。如果参加活动，也会列在参加者中。
start

object (DateOrDateTime)

开始时间（含）。对于重复活动，系统会使用第一个实例。
end

object (DateOrDateTime)

结束时间（不含）。对于重复性活动，系统会使用第一个实例。
recurrence[]

string

以 RRULE、EXRULE、RDATE 或 EXDATE 字符串（根据 RFC 5545）表示的重复规则。对于单个活动，此参数会被省略。必须在 start/end 字段中设置开始/结束时间。
recurringEventId

string

周期性活动实例的父周期性活动 ID。
originalStartTime

object (DateOrDateTime)

重复活动的原始开始时间。这是根据周期性重复数据，相应实例将开始运行的时间。
transparency
(deprecated)

string

可选。已弃用：请改用 availability。
visibility

string

可选。活动的公开范围。可能的值包括：

  • default - 使用日历中活动的默认公开范围。这是默认值。
  • public - 日历的所有读者都可以查看活动详情。
  • private - 只有活动参加者可以查看活动详情。
attendees[]

object (Attendee)

参加者。
conferenceUrl

string

视频会议链接。
colorId

string

活动的颜色。只会影响您自己的日历视图。这是指日历调色板中某个条目的 ID（字符串 '1'-'11'）：

  • 1：淡紫色
  • 2：Sage
  • 3：葡萄
  • 4：火烈鸟
  • 5：香蕉
  • 6：橘红
  • 7：Peacock
  • 8：石墨
  • 9：蓝莓
  • 10：罗勒绿
  • 11：番茄。
overrideReminders[]

object (Reminder)

提醒。如果未设置，则回退到日历默认值。
attachments[]

object (Attachment)

文件附件。
guestPermissions

object (GuestPermissions)

邀请对象权限。
eventType

enum (EventType)

事件类型。
workingLocationProperties

object (WorkingLocationProperties)

工作地点属性。仅当 event_type 为 WORKING_LOCATION 时填充。
availability

enum (Availability)

可选。空闲状态设置。

主账号

JSON 表示法 
{
  "email": string,
  "displayName": string,
  "self": boolean
}
字段
email

string

邮件、
displayName

string

名称。
self

boolean

仅限输出。相应正文是否与显示相应活动副本的日历相对应。默认值：false。

DateOrDateTime

JSON 表示法 
{
  "date": string,
  "dateTime": string,
  "timeZone": string
}
字段
date

string

午夜 UTC 时间的 ISO 8601 日期（例如 '2019-11-20T00:00:00Z'）。
dateTime

string

ISO 8601 时间戳（例如 '2019-11-20T08:19:06-07:00'）。
timeZone

string

TZDB 时区名称。

参加者

JSON 表示法 
{

  "id": string

  "email": string

  "displayName": string

  "organizer": boolean

  "self": boolean

  "resource": boolean

  "optionalAttendee": boolean

  "responseStatus": string

  "comment": string

  "additionalGuests": integer
}
字段

联合字段 _id。

_id 只能是下列其中一项：
id

string

仅限输出。个人资料 ID。

联合字段 _email。

_email 只能是下列其中一项：
email

string

必需。参会者的电子邮件地址。

联合字段 _display_name。

_display_name 只能是下列其中一项：
displayName

string

可选。名称。

联合字段 _organizer。

_organizer 只能是下列其中一项：
organizer

boolean

仅限输出。参会者是否为组织者。默认值：false。

联合字段 _self。

_self 只能是下列其中一项：
self

boolean

仅限输出。相应条目是否表示显示相应活动副本的日历。默认值：false。

联合字段 _resource。

_resource 只能是下列其中一项：
resource

boolean

可选。相应出席者是否为资源（例如会议室）。不可变，只能在最初添加参加者时设置。默认值：false。

联合字段 _optional_attendee。

_optional_attendee 只能是下列其中一项：
optionalAttendee

boolean

可选。参会者是否可选。默认值：false。

联合字段 _response_status。

_response_status 只能是下列其中一项：
responseStatus

string

可选。响应状态。可能的值包括：

  • needsAction - 参加者尚未回复邀请（建议用于新活动）。
  • declined - 受邀者已拒绝邀请。
  • tentative - 受邀者已暂时接受邀请。
  • accepted - 受邀者已接受邀请。

联合字段 _comment。

_comment 只能是下列其中一项：
comment

string

仅限输出。回答评论。

联合字段 _additional_guests。

_additional_guests 只能是下列其中一项：
additionalGuests

integer

可选。额外房客人数。默认值：0。

提醒

JSON 表示法 
{

  "method": string

  "minutes": integer
}
字段

联合字段 _method。

_method 只能是下列其中一项：
method

string

必需。投放方式。可能的值包括：

  • email - 系统会通过电子邮件发送提醒。
  • popup - 通过界面弹出式窗口发送提醒。

联合字段 _minutes。

_minutes 只能是下列其中一项：
minutes

integer

必需。提醒触发时间提前的分钟数。

附件

JSON 表示法 
{

  "fileUrl": string

  "title": string
}
字段

联合字段 _file_url。

_file_url 只能是下列其中一项：
fileUrl

string

必需。附件的网址链接。

联合字段 _title。

_title 只能是下列其中一项：
title

string

可选。附件标题。

GuestPermissions

JSON 表示法 
{

  "guestsCanInviteOthers": boolean

  "guestsCanModify": boolean

  "guestsCanSeeGuests": boolean
}
字段

联合字段 _guests_can_invite_others。

_guests_can_invite_others 只能是下列其中一项：
guestsCanInviteOthers

boolean

可选。邀请对象是否可以邀请他人。

联合字段 _guests_can_modify。

_guests_can_modify 只能是下列其中一项：
guestsCanModify

boolean

可选。邀请对象是否可以修改活动。

联合字段 _guests_can_see_guests。

_guests_can_see_guests 只能是下列其中一项：
guestsCanSeeGuests

boolean

可选。邀请对象是否可以查看其他邀请对象。

WorkingLocationProperties

JSON 表示法 
{

  "type": enum (WorkingLocationType)

  "customLocationLabel": string
}
字段

联合字段 _type。

_type 只能是下列其中一项：
type

enum (WorkingLocationType)

可选。工作地点类型。

联合字段 _custom_location_label。

_custom_location_label 只能是下列其中一项：
customLocationLabel

string

可选。自定义位置的标签。如果类型为 CUSTOM_LOCATION，则为必填项。

EventType

活动类型。一经创建便无法更改。

枚举
EVENT_TYPE_UNSPECIFIED 视为 DEFAULT。
DEFAULT 常规活动。默认值。
OUT_OF_OFFICE “不在办公室”活动。
FOCUS_TIME 专注时间活动。
WORKING_LOCATION 工作地点活动。
BIRTHDAY 每年举办一次的特殊全天活动。
FROM_GMAIL 来自 Gmail 的活动。无法创建此类活动。

WorkingLocationType

工作地点类型。

枚举
WORKING_LOCATION_TYPE_UNSPECIFIED 未指定工作地点类型。将被视为 HOME_OFFICE。
HOME_OFFICE 居家办公。
CUSTOM_LOCATION 自定义位置。

可用性

活动的空闲情况设置。

枚举
AVAILABILITY_UNSPECIFIED 默认值。视为 BUSY。
AVAILABILITY_BUSY 在日历上安排时间。
AVAILABILITY_FREE 不屏蔽时间。

工具注释

破坏性提示：❌ | 等幂性提示：❌ | 只读提示：❌ | 开放世界提示：❌

授权范围

需要以下 OAuth 范围之一：

  • https://www.googleapis.com/auth/calendar
  • https://www.googleapis.com/auth/calendar.events