Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

MCP Tools Reference: calendarmcp.googleapis.com

工具：`list_events`

返回指定日历中与所有指定限制条件匹配的活动。除非用户要求，否则不应指定时间限制。对于主日历上基于开放式关键字或主题的搜索，必须改用 search_events 工具。

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

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": "list_events",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

输入架构

ListEventsRequest

JSON 表示法

JSON 表示法
{ "eventTypeFilter": [ string ], "eventType": [ enum (`EventType`) ], "calendarId": string "pageSize": integer "pageToken": string "startTime": string "endTime": string "timeZone": string "orderBy": string "fullText": string }

{
  "eventTypeFilter": [
    string
  ],
  "eventType": [
    enum (EventType)
  ],

  "calendarId": string

  "pageSize": integer

  "pageToken": string

  "startTime": string

  "endTime": string

  "timeZone": string

  "orderBy": string

  "fullText": string
}

字段

字段
`eventTypeFilter[] (deprecated)`	`string` 此项已弃用！可选。已弃用：请改用 `event_type`。
`eventType[]`	`enum (EventType)` 可选。要返回的活动类型。如果为空，则仅返回以下事件类型：`DEFAULT`、`OUT_OF_OFFICE`、`FOCUS_TIME`、`FROM_GMAIL`
联合字段 `_calendar_id`。 `_calendar_id` 只能是下列其中一项：
`calendarId`	`string` 可选。包含活动的日历的 ID。电子邮件地址 - 可使用 `list_calendars` 进行解析。默认值：主日历。
联合字段 `_page_size`。 `_page_size` 只能是下列其中一项：
`pageSize`	`integer` 可选。每页的最大活动数（默认值为 `100`，最大值为 `250`）。建议值：`10`。
联合字段 `_page_token`。 `_page_token` 只能是下列其中一项：
`pageToken`	`string` 可选。下一页面令牌。使用上一页 `nextPageToken` 中的值。
联合字段 `_start_time`。 `_start_time` 只能是下列其中一项：
`startTime`	`string` 可选。时间范围的下限。仅在用户请求特定时间范围时设置。必须是小于 `end_time` 的 ISO 8601 时间戳。
联合字段 `_end_time`。 `_end_time` 只能是下列其中一项：
`endTime`	`string` 可选。时间范围的上限。仅当用户请求特定时间范围或过去的时间时，才必须设置此字段。必须是大于 `start_time` 的 ISO 8601 时间戳。
联合字段 `_time_zone`。 `_time_zone` 只能是下列其中一项：
`timeZone`	`string` 可选。用于解析不含时区的日期的时区（IANA ID，例如 `Europe/Zurich`）。默认值：日历的时区。
联合字段 `_order_by`。 `_order_by` 只能是下列其中一项：
`orderBy`	`string` 可选。应返回事件的顺序。可能的值包括： `default` - 未指定，但排序具有确定性（默认）。 `startTime` - 按开始时间升序排序。 `startTimeDesc` - 按开始时间降序排序。 `lastModified` - 按上次修改时间升序排序。
联合字段 `_full_text`。 `_full_text` 只能是下列其中一项：
`fullText`	`string` 可选。自由形式的不区分大小写的搜索，可匹配标题、说明、地点或参加者。匹配包含所有查询字词（按字面意思）的活动（AND 搜索）。

eventTypeFilter[]
(deprecated)

string

可选。已弃用：请改用 event_type。

eventType[]

enum (EventType)

可选。要返回的活动类型。如果为空，则仅返回以下事件类型：DEFAULT、OUT_OF_OFFICE、FOCUS_TIME、FROM_GMAIL

联合字段 _calendar_id。

_calendar_id 只能是下列其中一项：

calendarId

string

可选。包含活动的日历的 ID。电子邮件地址 - 可使用 list_calendars 进行解析。默认值：主日历。

联合字段 _page_size。

_page_size 只能是下列其中一项：

pageSize

integer

可选。每页的最大活动数（默认值为 100，最大值为 250）。建议值：10。

联合字段 _page_token。

_page_token 只能是下列其中一项：

pageToken

string

可选。下一页面令牌。使用上一页 nextPageToken 中的值。

联合字段 _start_time。

_start_time 只能是下列其中一项：

startTime

string

可选。时间范围的下限。仅在用户请求特定时间范围时设置。必须是小于 end_time 的 ISO 8601 时间戳。

联合字段 _end_time。

_end_time 只能是下列其中一项：

endTime

string

可选。时间范围的上限。仅当用户请求特定时间范围或过去的时间时，才必须设置此字段。必须是大于 start_time 的 ISO 8601 时间戳。

联合字段 _time_zone。

_time_zone 只能是下列其中一项：

timeZone

string

可选。用于解析不含时区的日期的时区（IANA ID，例如 Europe/Zurich）。默认值：日历的时区。

联合字段 _order_by。

_order_by 只能是下列其中一项：

orderBy

string

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

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

联合字段 _full_text。

_full_text 只能是下列其中一项：

fullText

string

可选。自由形式的不区分大小写的搜索，可匹配标题、说明、地点或参加者。匹配包含所有查询字词（按字面意思）的活动（AND 搜索）。

EventType

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

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

输出架构

ListEventsResponse

JSON 表示法

JSON 表示法
{ "summary": string, "description": string, "updated": string, "timeZone": string, "accessRole": string, "defaultReminders": [ { object (`Reminder`) } ], "events": [ { object (`Event`) } ], "nextPageToken": string }

{
  "summary": string,
  "description": string,
  "updated": string,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      object (Reminder)
    }
  ],
  "events": [
    {
      object (Event)
    }
  ],

  "nextPageToken": string
}

字段
`summary`	`string` 日历的标题。
`description`	`string` 日历的说明。
`updated`	`string` 日历的上次更新时间 (ISO 8601)。
`timeZone`	`string` 日历的时区。
`accessRole`	`string` 仅限输出。用户对日历的访问角色。可能的值包括： `none` - 无访问权限。 `freeBusyReader` - 拥有有空/忙碌信息的读取权限。 `reader` - 对日历拥有读取权限。系统会显示不公开的活动，但会隐藏活动详细信息。 `writer` - 读写权限。系统会显示不公开活动，并且活动详情可见。 `owner` - 管理员访问权限，包括修改日历共享设置的权限。重要提示：`owner` 角色与日历的数据所有者不同。日历只有一个数据所有者，但可以有多个具有 `owner` 角色的用户。
`defaultReminders[]`	`object (Reminder)` 日历中活动的默认提醒。
`events[]`	`object (Event)` 事件列表。
联合字段 `_next_page_token`。 `_next_page_token` 只能是下列其中一项：
`nextPageToken`	`string` 下一页面令牌。如果不存在下一页，则省略。

提醒

JSON 表示法
{ "method": string "minutes": integer }

字段

字段
联合字段 `_method`。 `_method` 只能是下列其中一项：
`method`	`string` 必需。投放方式。可能的值包括： `email` - 系统会通过电子邮件发送提醒。 `popup` - 通过界面弹出式窗口发送提醒。
联合字段 `_minutes`。 `_minutes` 只能是下列其中一项：
`minutes`	`integer` 必需。提醒触发时间提前的分钟数。

联合字段 _method。

_method 只能是下列其中一项：

method

string

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

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

联合字段 _minutes。

_minutes 只能是下列其中一项：

minutes

integer

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

活动

JSON 表示法

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,
  "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`。

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 时区名称。

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 }

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`。

联合字段 _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 表示法
{ "fileUrl": string "title": string }

字段

字段
联合字段 `_file_url`。 `_file_url` 只能是下列其中一项：
`fileUrl`	`string` 必需。附件的网址链接。
联合字段 `_title`。 `_title` 只能是下列其中一项：
`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` 可选。邀请对象是否可以查看其他邀请对象。

联合字段 _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`，则为必填项。

联合字段 _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
https://www.googleapis.com/auth/calendar.events.readonly
https://www.googleapis.com/auth/calendar.readonly

MCP Tools Reference: calendarmcp.googleapis.com 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

工具：list_events

输入架构

ListEventsRequest

EventType

输出架构

ListEventsResponse

提醒

活动

主账号

DateOrDateTime

参加者

附件

GuestPermissions

WorkingLocationProperties

EventType

WorkingLocationType

可用性

工具注释

授权范围

MCP Tools Reference: calendarmcp.googleapis.com

工具：`list_events`