MCP Tools Reference: calendarmcp.googleapis.com

string

可选。要返回的事件类型。可能的值包括：

• default - 常规活动（默认）。
• outOfOffice - “不在办公室”活动。
• focusTime - 专注时间活动。
• workingLocation - 工作地点活动。
• birthday - 生日活动。
• fromGmail - 来自 Gmail 的活动。

如果为空，则仅返回以下事件类型：default、outOfOffice、focusTime、fromGmail

string

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

integer

可选。一个结果页面中返回的事件数上限。即使有更多事件与查询匹配，结果页面中的事件数也可能小于此值，甚至可能没有事件。如果响应中的 next_page_token 字段不为空，则表示检测到不完整的网页。默认情况下，值为 250 个事件。网页大小永远不能超过 2,500 个事件。

string

可选。用于指定要返回哪个结果页面的令牌。

string

可选。活动结束时间的下限（不含）。系统仅返回严格晚于此时间的结束时间（即搜索时间窗口的开始时间）。如果未提供 start_time 和 end_time，则默认为当前时间。如果指定，则必须小于或等于 end_time。必须是 ISO 8601 时间戳。例如，2026-06-03T10:00:00-07:00、2026-06-03T10:00:00Z 或 2026-06-03T10:00:00。可以提供毫秒，但系统会忽略。

string

可选。活动的开始时间上限（不含）。系统只会返回严格在此时间之前开始的活动（即搜索时间窗口的结束时间）。如果指定，则必须大于或等于 start_time。必须是 ISO 8601 时间戳。例如，2026-06-03T10:00:00-07:00、2026-06-03T10:00:00Z 或 2026-06-03T10:00:00。可以提供毫秒，但系统会忽略。

string

可选。响应中使用的时区以及用于解析请求中不含时区的日期的时区（格式采用 IANA 时区数据库名称，例如 Europe/Zurich）。默认值为日历的时区。

string

可选。应返回事件的顺序。可能的值包括：

• default - 未指定，但排序具有确定性（默认）。
• startTime - 按开始时间升序排序。
• startTimeDesc - 按开始时间降序排序。
• lastModified - 按上次修改时间升序排序。

string

可选。自由格式的搜索查询，用于搜索标题、说明、地点和参加者。

string

日历的标题。

string

日历的说明。

string

日历的上次修改时间（以 ISO 8601 时间戳的形式表示）。

string

日历的时区。

string

相应日历的用户访问角色。只读。可能的值包括：

• none - 用户无权访问。
• freeBusyReader - 用户拥有有空/忙碌信息的读取权限。
• reader - 用户拥有日历的读取权限。不公开活动会向具有读取权限的用户显示，但活动详情会被隐藏。
• writer - 用户拥有对日历的读写权限。具有写入权限的用户会看到不公开活动，并且可以看到活动详情。
• owner - 用户拥有日历的经理访问权限。此角色具有写入者角色的所有权限，此外还能够查看和修改其他用户的访问权限级别。重要提示：所有者角色与日历的数据所有者不同。一个日历只能有一个数据所有者，但可以有多个具有所有者角色的用户。

object (Reminder)

已通过身份验证的用户的日历上的默认提醒。这些提醒适用于相应日历中的所有活动，除非这些活动明确替换了这些提醒（即，将 reminders.useDefault 设置为 True）。

object (Event)

日历中的活动列表。

string

用于访问相应结果的下一页的令牌。如果没有更多结果，则省略此字段。

string

向用户发送提醒的方式。可能的值包括：

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

添加提醒时需要提供。

integer

提醒应提前多少分钟发送。

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。

string

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

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

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

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

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

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

string

Google 日历 Web 界面中相应活动的绝对链接。只读。

string

事件的创建时间（采用 ISO 8601 格式的时间戳）。只读。

string

主要事件数据的上次修改时间（采用 ISO 8601 格式的时间戳）。更新活动提醒不会导致此设置发生变化。只读。

string

活动的标题。

string

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

string

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

object (Principal)

活动的创建者。只读。

object (Principal)

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

object (DateOrDateTime)

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

object (DateOrDateTime)

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

string

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

string

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

object (DateOrDateTime)

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

string

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

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

string

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

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

object (Attendee)

活动的参加者。

string

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

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

string

活动的 Google Meet 链接。

string

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

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

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

string

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

string

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

boolean

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

string

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

string

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

string

TZDB 时区名称（如果有）。

string

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

string

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

string

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

boolean

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

boolean

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

boolean

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

boolean

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

string

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

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

string

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

integer

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