MCP Tools Reference: calendarmcp.googleapis.com

工具:search_events

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

以下代码示例展示了如何使用 curl 调用 search_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": "search_events",
    "arguments": {
      // Provide these details according to the MCP tool 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,
  "conferenceData": {
    object (EventConferenceData)
  },
  "colorId": string,
  "overrideReminders": [
    {
      object (Reminder)
    }
  ],
  "attachments": [
    {
      object (Attachment)
    }
  ],
  "guestPermissions": {
    object (GuestPermissions)
  },
  "eventType": enum (EventType),
  "workingLocationProperties": {
    object (WorkingLocationProperties)
  },
  "availability": enum (Availability),
  "label": {
    object (Label)
  },
  "taskId": string,

  "useDefaultReminders": boolean
}
字段
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
(deprecated)

string

已弃用:请改用 conferenceData.videoEntryPoint.uri。视频会议链接。

conferenceData

object (EventConferenceData)

会议数据,包括视频会议链接(如有)。

colorId

string

活动的颜色。对拥有日历编辑权限的用户可见。

这是指日历调色板中条目的 ID(字符串 '1'-'11'):

  • 1:薄暮紫
  • 2:灰绿色
  • 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)

工作地点属性。仅当 eventType 为 WORKING_LOCATION 时填充。

availability

enum (Availability)

可选。空闲状态设置。

label

object (Label)

仅限输出。分配给此事件的标签。仅在事件有标签时填充。对拥有日历编辑权限的用户可见。

taskId

string

仅限输出。此活动对应的时间块所属的 Google Tasks 任务的 ID。仅当 eventType 为 FOCUS_TIME 且事件与任务关联时,系统才会填充此字段。

联合字段 _use_default_reminders。

_use_default_reminders 只能是下列其中一项:

useDefaultReminders

boolean

是否对活动使用默认提醒。如果此字段为 false 且 overrideReminders 为空,则表示该活动没有提醒。修改只会影响操作用户的视图。

主体

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

string

邮件、

displayName

string

名称。

self

boolean

仅限输出。此主账号是否对应于显示此活动副本的日历。默认值:false。

DateOrDateTime

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

string

采用 yyyy-mm-dd 格式的 ISO 8601 日期(例如 '2019-11-20')。

dateTime

string

ISO 8601 时间戳(例如 '2019-11-20T08:19:06-07:00')。

timeZone

string

采用 IANA 时区数据库格式的原始时区(例如 'America/Los_Angeles')。返回的 dateTime 可能会采用不同的显示时区(例如查看者的当前时区)。

参加者

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。

EventConferenceData

JSON 表示法
{
  "solutionName": string,
  "joiningNotesText": string,
  "videoEntryPoint": {
    object (EntryPoint)
  },
  "phoneEntryPoints": [
    {
      object (PhoneEntryPoint)
    }
  ],
  "sipEntryPoint": {
    object (EntryPoint)
  },
  "moreDetailsEntryPoint": {
    object (EntryPoint)
  }
}
字段
solutionName

string

会议解决方案的名称。

joiningNotesText

string

会议加入说明。

videoEntryPoint

object (EntryPoint)

视频入口点。

phoneEntryPoints[]

object (PhoneEntryPoint)

电话入口点列表。

sipEntryPoint

object (EntryPoint)

SIP 入口点。

moreDetailsEntryPoint

object (EntryPoint)

其他加入说明。

EntryPoint

JSON 表示法
{
  "uri": string,
  "codes": [
    {
      object (Code)
    }
  ]
}
字段
uri

string

入口点 URI,可能是 SIP、视频或自由文本字符串,如需了解详情,请参阅相关文档。

codes[]

object (Code)

使用此入口点所需的代码(例如访问代码、密码)。

代码

JSON 表示法
{
  "codeType": enum (CodeType),
  "value": string
}
字段
codeType

enum (CodeType)

代码类型

value

string

代码本身,例如“123456”“abcde”。

PhoneEntryPoint

JSON 表示法
{
  "phoneNumber": string,
  "codes": [
    {
      object (Code)
    }
  ],
  "regionCode": string,
  "isTollNumber": boolean
}
字段
phoneNumber

string

用于加入电话会议的电话号码。

codes[]

object (Code)

使用此电话号码加入会议时需要输入的代码(例如 PIN 码)。

regionCode

string

与此电话访问权限关联的国家/地区的地区代码。

isTollNumber

boolean

此电话号码是否为收费电话。

提醒

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,
  "officeLocation": {
    object (OfficeLocationDetails)
  }

  "timeZone": string
}
字段

联合字段 _type。

_type 只能是下列其中一项:

type

enum (WorkingLocationType)

可选。工作地点类型。

联合字段 location。特定于位置的详细信息。location 只能是下列其中一项:
customLocationLabel

string

可选。自定义位置的标签。如果类型为 CUSTOM_LOCATION,则必须提供此值。

officeLocation

object (OfficeLocationDetails)

可选。办公室位置详细信息。如果类型为 OFFICE_LOCATION,则必须提供此值。

联合字段 _time_zone。

_time_zone 只能是下列其中一项:

timeZone

string

仅限输出。时区(IANA 时区数据库名称,例如“America/Los_Angeles”)。

OfficeLocationDetails

JSON 表示法
{

  "buildingId": string

  "floorId": string

  "floorSectionId": string

  "deskId": string

  "label": string
}
字段

联合字段 _building_id。

_building_id 只能是下列其中一项:

buildingId

string

可选。建筑物 ID。

联合字段 _floor_id。

_floor_id 只能是下列其中一项:

floorId

string

可选。楼层 ID。

联合字段 _floor_section_id。

_floor_section_id 只能是下列其中一项:

floorSectionId

string

可选。楼层分区 ID。

联合字段 _desk_id。

_desk_id 只能是下列其中一项:

deskId

string

可选。桌子 ID。

联合字段 _label。

_label 只能是下列其中一项:

label

string

可选。办公地点的直观易懂标签。

标签

JSON 表示法
{
  "id": string,
  "displayName": string,
  "backgroundColor": string
}
字段
id

string

仅限输出。唯一标识符。

displayName

string

可选。显示名称(最多 50 个字符)。

backgroundColor

string

必需。十六进制格式的背景颜色(例如“#039be5”)。

CodeType

有效的代码类型。

枚举
CODE_TYPE_UNSPECIFIED 切勿使用未指定。
ACCESS_CODE 访问代码。
PASSCODE 密码。
PASSWORD 密码。
MEETING_CODE 会议代码。
PIN PIN 码。

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 自定义位置。
OFFICE_LOCATION 办公地点。

可用性

活动的空闲状态设置。

枚举
AVAILABILITY_UNSPECIFIED 默认值。视为 BUSY。
AVAILABILITY_BUSY 在日历上预留时间。
AVAILABILITY_FREE 不占用时间。

工具注释

工具注解会发送到 MCP 客户端,用于描述给定工具的基本风险。大多数客户端会将这些提示视为不可信,但它们可用于决定何时向用户发送确认提示。

除了标题字符串之外,还定义了以下布尔值提示:

  • readOnlyHint:如果为 true,则该工具不会修改其环境。默认值:false。
  • destructiveHint:如果为 true,则该工具可以执行破坏性操作。如果为 false,则该工具只能执行添加操作。默认值:true。
  • idempotentHint:如果为 true,则使用相同参数重复调用该工具不会对其环境产生额外影响。默认值:false。
  • openWorldHint:如果为 true,则该工具可以与外部实体的“开放世界”进行交互。如果为 false,则该工具只能与内部实体交互。例如,网页搜索工具是开放式的,而记忆工具不是开放式的。

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

授权范围

需要以下 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