MCP Tools Reference: calendarmcp.googleapis.com

工具：search_events

使用语义搜索功能搜索用户主日历中的活动。

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

输入架构

针对 SearchEvents 的请求消息。

SearchEventsRequest

JSON 表示法 
{
  "query": string,

  "pageSize": integer

  "pageToken": string
}
字段
query

string

必需。用于搜索活动（不区分大小写）的查询字符串。

联合字段 _page_size。

_page_size 只能是下列其中一项：
pageSize

integer

可选。一个结果页面中返回的条目数上限。

联合字段 _page_token。

_page_token 只能是下列其中一项：
pageToken

string

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

输出架构

SearchEvents 的响应消息。

SearchEventsResponse

JSON 表示法 
{
  "events": [
    {
      object (Event)
    }
  ],

  "nextPageToken": string
}
字段
events[]

object (Event)

与查询匹配的事件列表。

联合字段 _next_page_token。

_next_page_token 只能是下列其中一项：
nextPageToken

string

用于访问相应结果的下一页的令牌。

事件

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 不屏蔽时间。

工具注释

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