MCP Tools Reference: calendarmcp.googleapis.com

工具：create_event

创建日历活动。

此工具适用于以下类型的查询：

  • 在我的日历上创建一项活动，活动名称为“与 Jane 会面”，时间为明天下午 2 点。
  • 安排下周一上午 10 点到 11 点与 john.doe@google.com 开会。

示例：

create_event(
            summary='Meeting with Jane',
            startTime='2024-09-17T14:00:00',
            endTime='2024-09-17T15:00:00'
        )
        # Creates an event on the primary calendar for September 17, 2024 from 2pm to 3pm called 'Meeting with Jane'.

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

Curl 请求 
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
}'

输入架构

针对 CreateEvent 的请求消息。

CreateEventRequest

JSON 表示法 
{
  "summary": string,
  "startTime": string,
  "endTime": string,
  "attendeeEmails": [
    string
  ],
  "recurrenceData": [
    string
  ],

  "calendarId": string

  "description": string

  "location": string

  "allDay": boolean

  "timeZone": string

  "notificationLevel": enum (NotificationLevel)

  "addGoogleMeetUrl": boolean

  "visibility": string

  "colorId": string

  "googleMeetUrl": string
}
字段
summary

string

必需。活动的标题。
startTime

string

必需。活动的开始时间，采用 ISO 8601 格式。
endTime

string

必需。活动的结束时间，采用 ISO 8601 格式。
attendeeEmails[]

string

可选。活动的额外参加者（以电子邮件地址的形式）。
recurrenceData[]

string

可选。事件的重复数据，格式为 RRULE、RDATE 或 EXDATE（根据 RFC 5545）。使用此字段可创建周期性活动。

联合字段 _calendar_id。

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

string

可选。要在哪个日历中创建活动。默认值为用户的主日历。

联合字段 _description。

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

string

可选。活动的说明。可以包含 HTML。

联合字段 _location。

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

string

可选。活动的地理位置（自由格式文本）。

联合字段 _all_day。

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

boolean

可选。活动是否为全天活动。默认值为 False。如果为 true，则开始时间和结束时间必须设置为世界协调时间 (UTC) 的午夜。

联合字段 _time_zone。

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

string

可选。活动的时区（格式采用 IANA 时区数据库名称，例如“Europe/Zurich”）。可选，但建议提供。它还用于解析请求中不含时区的日期。默认值为日历的时区。

联合字段 _notification_level。

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

enum (NotificationLevel)

可选。应针对此活动更新发送哪种电子邮件通知。可能的值包括：

  • NONE - 不发送电子邮件通知（默认）。
  • EXTERNAL_ONLY - 只有外部（非日历）出席者会收到电子邮件通知。
  • ALL - 所有活动参加者都会收到电子邮件通知。

联合字段 _add_google_meet_url。

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

boolean

可选。允许为活动创建 Google Meet 网址。默认情况下，不会创建 Google Meet 网址。如果为用户停用了 Meet，则不会创建 Google Meet 网址，但活动创建会成功。

联合字段 _visibility。

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

string

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

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

联合字段 _color_id。

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

string

可选。活动的颜色。此 ID 是指日历调色板中的某个条目。活动颜色 ID（字符串 1-11）：

  • 1：淡紫色
  • 2：Sage
  • 3：葡萄
  • 4：火烈鸟
  • 5：香蕉
  • 6：橘红
  • 7：Peacock
  • 8：石墨
  • 9：蓝莓色
  • 10：巴塞尔
  • 11：番茄。

联合字段 _google_meet_url。

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

string

可选。允许将现有 Google Meet 网址或会议 ID 附加到活动。如果设置了此网址，系统会将此网址附加到活动中，而不是生成新的 Google Meet 会议室，即使 add_google_meet_url 设置为 true 也是如此。

输出架构

事件

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)
    }
  ],
  "eventType": string,
  "conferenceUrl": string,
  "colorId": string
}
字段
id

string

相应事件的不透明标识符。创建新的单次活动或周期性活动时，您可以指定其 ID。提供的 ID 必须遵循以下规则：

  • ID 中允许使用的字符是 base32hex 编码中使用的字符，即小写字母 a-v 和数字 0-9，请参阅 RFC2938 中的第 3.1.2 节
  • ID 的长度必须介于 5 到 1024 个字符之间
  • 每个日历的 ID 必须是唯一的

由于该系统是全球分布式的，因此我们无法保证在创建活动时检测到 ID 冲突。为最大限度地降低冲突风险，我们建议使用已确立的 UUID 算法，例如 RFC4122 中所述的算法。

如果您未指定 ID，服务器会自动生成一个 ID。

请注意，icalUID 和 ID 并不相同，在创建活动时只能提供其中一个。在语义上，两者之间的一个区别在于，在周期性活动中，一个活动的所有实例都具有不同的 ID，但它们都共享相同的 icalUID。
status

string

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

  • confirmed - 活动已确认。这是默认状态。
  • tentative - 活动已暂时确认。
  • cancelled - 活动已取消（已删除）。仅在增量同步（指定了 syncToken 或 updatedMin）或 showDeleted 标志设置为 true 时，list 方法才会返回已取消的活动。get 方法始终会返回这些值。

“已取消”状态表示两种不同的状态，具体取决于活动类型：

  1. 未取消的周期性活动的已取消例外情况表示相应实例不应再向用户显示。客户端应在父周期性活动的整个生命周期内存储这些事件。系统仅保证已取消的例外情况会填充 id、recurringEventId 和 originalStartTime 字段的值。其他字段可能为空。
  2. 所有其他已取消的活动都表示已删除的活动。客户应移除本地同步的副本。此类已取消的活动最终会消失，因此请勿指望它们会无限期保留。已删除的事件仅保证填充了 id 字段。

在组织者的日历中，已取消的活动会继续显示活动详情（摘要、地点等），以便组织者恢复（取消删除）这些活动。同样，用户受邀参加但手动移除的活动也会继续提供详细信息。不过，如果增量同步请求的 showDeleted 设置为 false，则不会返回这些详细信息。

如果活动更改了组织者（例如通过移动操作），并且原始组织者不在参加者列表中，则会留下一个已取消的活动，其中只有 id 字段保证已填充。
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)

活动的组织者。如果组织者也是参会者，则会在参会者中单独添加一个条目，并将组织者字段设置为 True。只读。
start

object (DateOrDateTime)

活动的开始时间（含）。对于周期性活动，这是第一个实例的开始时间。
end

object (DateOrDateTime)

活动的结束时间（不含）。对于周期性活动，这是第一个实例的结束时间。
recurrence[]

string

周期性活动的 RRULE、EXRULE、RDATE 和 EXDATE 行的列表，如 RFC5545 中所指定。请注意，此字段中不允许使用 DTSTART 和 DTEND 行；活动开始时间和结束时间在 start 和 end 字段中指定。对于单次活动或周期性活动的实例，此字段会被省略。
recurringEventId

string

对于周期性活动的实例，这是相应实例所属的周期性活动的 ID。固定不变。
originalStartTime

object (DateOrDateTime)

对于周期性活动的某个实例，这是根据由 recurringEventId 标识的周期性活动中的周期性数据，该活动应开始的时间。即使实例已移至其他时间，它也能在周期性活动系列中唯一标识该实例。固定不变。
transparency

string

相应活动是否会占用日历中的时间。可选。可能的值包括：

  • opaque - 默认值。活动会占用日历中的时间。这相当于在日历界面中将“将我显示为”设置为“忙碌”。
  • transparent - 活动不会占用日历中的时间。这相当于在日历界面中将“显示为”设置为“有空”。
visibility

string

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

  • default - 使用日历中活动的默认公开范围。这是默认值。
  • public - 活动是公开的，日历的所有读者都可以查看活动详情。
  • private - 活动是不公开的，只有活动参与者可以查看活动详情。
  • confidential - 活动为非公开活动。提供此值是为了保持兼容性。
attendees[]

object (Attendee)

活动的参加者。
eventType

string

具体事件类型。活动创建后，此设置将无法修改。可能的值包括：

  • birthday - 一种特殊的全天活动，每年重复一次。
  • default - 常规活动或未进一步指定。
  • focusTime - 专注时间活动。
  • fromGmail - 来自 Gmail 的活动。无法创建此类活动。
  • outOfOffice -“不在办公室”活动。
  • workingLocation - 工作地点事件。
conferenceUrl

string

活动的 Google Meet 链接。
colorId

string

活动颜色 ID（字符串 1-11）：

  • 1：淡紫色
  • 2：Sage
  • 3：葡萄
  • 4：火烈鸟
  • 5：香蕉
  • 6：橘红
  • 7：Peacock
  • 8：石墨
  • 9：蓝莓色
  • 10：巴塞尔
  • 11：番茄。

在 Google 日历中，活动颜色用作类别，可以按活动或按系列进行设置。用户可以在网页界面中为颜色分配自定义标签（例如 1:1s、Break），但 API 仅公开数字 ID，而不公开这些标签。仅影响您自己的日历视图，每位出席者都可以控制自己的活动颜色。

主账号

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

string

主账号（日历）的电子邮件地址。
displayName

string

主账号的名称（如果有）。
self

boolean

相应正文是否与显示此活动副本的日历相对应。只读。默认值为 False。

DateOrDateTime

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

string

采用 ISO 8601 格式的日期（UTC 午夜），例如 2019-11-20T00:00:00Z。如果设置了此字段，则不得设置 date_time。
dateTime

string

采用 ISO 8601 格式的时间戳，例如 2019-11-20T08:19:06-07:00 或 2019-11-20T08:19:06Z。如果设置了此字段，则不得设置 date。
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

string

参会者的个人资料 ID（如果有）。
email

string

参会者的电子邮件地址（如有）。添加参会者时，必须提供此字段。必须是有效的电子邮件地址（符合 RFC5322 的规定）。添加参会者时必须指定这项设置。
displayName

string

参会者的姓名（如果有）。可选。
organizer

boolean

相应参加者是否为活动的组织者。只读。默认值为 False。
self

boolean

相应条目是否表示显示相应活动副本的日历。只读。默认值为 False。
resource

boolean

相应出席者是否为资源。只能在首次将参会者添加到活动时设置。后续修改会被忽略。可选。默认值为 False。
optionalAttendee

boolean

相应人员是否为可选参加者。可选。默认值为 False。
responseStatus

string

参会者的回复状态。可能的值包括：

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

string

参加者的回答评论。可选。
additionalGuests

integer

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

工具注释

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