MCP Tools Reference: calendarmcp.googleapis.com

工具：update_event

更新日历活动。

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

  • 将“与 Jane 的会议”活动更新为一小时后。
  • 将 john.doe@google.com 添加到明天的会议中。

示例：

update_event(
            eventId='event123',
            summary='Meeting with Jane and John'
        )
        # Updates the summary of event with id 'event123' on the primary calendar to 'Meeting with Jane and John'.

以下示例演示了如何使用 curl 调用 update_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": "update_event",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

针对 UpdateEvent 的请求消息。

UpdateEventRequest

JSON 表示法 
{
  "eventId": string,
  "addedAttendeeEmails": [
    string
  ],
  "removedAttendeeEmails": [
    string
  ],

  "calendarId": string

  "summary": string

  "description": string

  "location": string

  "startTime": string

  "endTime": string

  "notificationLevel": enum (NotificationLevel)

  "addGoogleMeetUrl": boolean

  "visibility": string

  "colorId": string

  "googleMeetUrl": string
}
字段
eventId

string

必需。要更新的活动的 ID。
addedAttendeeEmails[]

string

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

string

可选。要移除的活动参加者（以电子邮件地址的形式）。

联合字段 _calendar_id。

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

string

可选。要更新的活动的日历 ID。默认值为用户的主日历。

联合字段 _summary。

_summary 只能是下列其中一项：
summary

string

可选。活动的新标题。如果未设置，则不会更新。

联合字段 _description。

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

string

可选。活动的新说明。如果未设置，则不会更新。

联合字段 _location。

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

string

可选。活动的新地点。如果未设置，则不会更新。

联合字段 _start_time。

_start_time 只能是下列其中一项：
startTime

string

可选。活动的新的开始时间，采用 ISO 8601 格式。如果未设置，则不会更新。

联合字段 _end_time。

_end_time 只能是下列其中一项：
endTime

string

可选。活动的新的结束时间，采用 ISO 8601 格式。如果未设置，则不会更新。

联合字段 _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。

工具注释

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