工具: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 |
必需。用于搜索事件的查询字符串(不区分大小写)。 |
联合字段
|
|
pageSize |
可选。一个结果页上返回的条目数上限。 |
联合字段
|
|
pageToken |
可选。指定要返回的结果页面的令牌。 |
输出架构
SearchEvents 的响应消息。
SearchEventsResponse
| JSON 表示法 |
|---|
{
"events": [
{
object ( |
| 字段 | |
|---|---|
events[] |
与查询匹配的事件列表。 |
联合字段
|
|
nextPageToken |
用于访问此结果下一页的令牌。 |
活动
| JSON 表示法 |
|---|
{ "id": string, "status": string, "htmlLink": string, "created": string, "updated": string, "summary": string, "description": string, "location": string, "creator": { object ( |
| 字段 | |
|---|---|
id |
唯一标识符。 |
status |
可选。状态。可能的值包括:
|
htmlLink |
仅限输出。Google 日历 Web 界面中此活动的绝对链接。 |
created |
仅限输出。创建时间 (ISO 8601)。 |
updated |
仅限输出。上次修改时间 (ISO 8601)。 |
summary |
标题。 |
description |
可选。说明。可包含 HTML。 |
location |
可选。位置信息。 |
creator |
仅限输出。创作者。 |
organizer |
仅限输出。组织者。如果参加,也会列在参加者中。 |
start |
开始时间(含)。对于周期性活动,系统会使用第一个实例。 |
end |
结束时间(不含)。对于周期性活动,系统会使用第一个实例。 |
recurrence[] |
重复规则,采用 |
recurringEventId |
周期性活动实例的父级周期性活动 ID。 |
originalStartTime |
周期性实例的原始开始时间。这是根据定期重复数据,此实例开始的时间。 |
transparency |
可选。已弃用:请改用 |
visibility |
可选。活动的公开范围。可能的值包括:
|
attendees[] |
参加者。 |
conferenceUrl |
已弃用:请改用 |
conferenceData |
会议数据,包括视频会议链接(如有)。 |
colorId |
活动的颜色。对拥有日历编辑权限的用户可见。 这是指日历调色板中条目的 ID(字符串
|
overrideReminders[] |
替换提醒,用于替换活动的默认提醒。修改只会影响操作用户的视图。 |
attachments[] |
文件附件。 |
guestPermissions |
邀请对象权限。 |
eventType |
事件类型。 |
workingLocationProperties |
工作地点属性。仅当 |
availability |
可选。空闲状态设置。 |
label |
仅限输出。分配给此事件的标签。仅在事件有标签时填充。对拥有日历编辑权限的用户可见。 |
taskId |
仅限输出。此活动对应的时间块所属的 Google Tasks 任务的 ID。仅当 |
联合字段
|
|
useDefaultReminders |
是否对活动使用默认提醒。如果此字段为 false 且 |
主体
| JSON 表示法 |
|---|
{ "email": string, "displayName": string, "self": boolean } |
| 字段 | |
|---|---|
email |
邮件、 |
displayName |
名称。 |
self |
仅限输出。此主账号是否对应于显示此活动副本的日历。默认值: |
DateOrDateTime
| JSON 表示法 |
|---|
{ "date": string, "dateTime": string, "timeZone": string } |
| 字段 | |
|---|---|
date |
采用 |
dateTime |
ISO 8601 时间戳(例如 |
timeZone |
采用 IANA 时区数据库格式的原始时区(例如 |
参加者
| JSON 表示法 |
|---|
{ "id": string "email": string "displayName": string "organizer": boolean "self": boolean "resource": boolean "optionalAttendee": boolean "responseStatus": string "comment": string "additionalGuests": integer } |
| 字段 | |
|---|---|
联合字段
|
|
id |
仅限输出。个人资料 ID。 |
联合字段
|
|
email |
必需。参加者的邮箱。 |
联合字段
|
|
displayName |
可选。名称。 |
联合字段
|
|
organizer |
仅限输出。参加者是否为组织者。默认值: |
联合字段
|
|
self |
仅限输出。此条目是否代表显示此活动副本的日历。默认值: |
联合字段
|
|
resource |
可选。参加者是否为资源(例如会议室)。不可变,只能在最初添加参加者时设置。默认值: |
联合字段
|
|
optionalAttendee |
可选。参加者是否为可选。默认值: |
联合字段
|
|
responseStatus |
可选。响应状态。可能的值包括:
|
联合字段
|
|
comment |
仅限输出。回复评论。 |
联合字段
|
|
additionalGuests |
可选。额外房客人数。默认值: |
EventConferenceData
| JSON 表示法 |
|---|
{ "solutionName": string, "joiningNotesText": string, "videoEntryPoint": { object ( |
| 字段 | |
|---|---|
solutionName |
会议解决方案的名称。 |
joiningNotesText |
会议加入说明。 |
videoEntryPoint |
视频入口点。 |
phoneEntryPoints[] |
电话入口点列表。 |
sipEntryPoint |
SIP 入口点。 |
moreDetailsEntryPoint |
其他加入说明。 |
EntryPoint
| JSON 表示法 |
|---|
{
"uri": string,
"codes": [
{
object ( |
| 字段 | |
|---|---|
uri |
入口点 URI,可能是 SIP、视频或自由文本字符串,如需了解详情,请参阅相关文档。 |
codes[] |
使用此入口点所需的代码(例如访问代码、密码)。 |
代码
| JSON 表示法 |
|---|
{
"codeType": enum ( |
| 字段 | |
|---|---|
codeType |
代码类型 |
value |
代码本身,例如“123456”“abcde”。 |
PhoneEntryPoint
| JSON 表示法 |
|---|
{
"phoneNumber": string,
"codes": [
{
object ( |
| 字段 | |
|---|---|
phoneNumber |
用于加入电话会议的电话号码。 |
codes[] |
使用此电话号码加入会议时需要输入的代码(例如 PIN 码)。 |
regionCode |
与此电话访问权限关联的国家/地区的地区代码。 |
isTollNumber |
此电话号码是否为收费电话。 |
提醒
| JSON 表示法 |
|---|
{ "method": string "minutes": integer } |
| 字段 | |
|---|---|
联合字段
|
|
method |
必需。投放方式。可能的值包括:
|
联合字段
|
|
minutes |
必需。提前多少分钟触发提醒。 |
附件
| JSON 表示法 |
|---|
{ "fileUrl": string "title": string } |
| 字段 | |
|---|---|
联合字段
|
|
fileUrl |
必需。指向附件的网址链接。 |
联合字段
|
|
title |
可选。附件标题。 |
GuestPermissions
| JSON 表示法 |
|---|
{ "guestsCanInviteOthers": boolean "guestsCanModify": boolean "guestsCanSeeGuests": boolean } |
| 字段 | |
|---|---|
联合字段
|
|
guestsCanInviteOthers |
可选。邀请对象是否可以邀请他人。 |
联合字段
|
|
guestsCanModify |
可选。邀请对象是否可以修改活动。 |
联合字段
|
|
guestsCanSeeGuests |
可选。邀请对象是否可以看到其他邀请对象。 |
WorkingLocationProperties
| JSON 表示法 |
|---|
{ "type": enum ( |
| 字段 | |
|---|---|
联合字段
|
|
type |
可选。工作地点类型。 |
联合字段 location。特定于位置的详细信息。location 只能是下列其中一项: |
|
customLocationLabel |
可选。自定义位置的标签。如果类型为 |
officeLocation |
可选。办公室位置详细信息。如果类型为 |
联合字段
|
|
timeZone |
仅限输出。时区(IANA 时区数据库名称,例如“America/Los_Angeles”)。 |
OfficeLocationDetails
| JSON 表示法 |
|---|
{ "buildingId": string "floorId": string "floorSectionId": string "deskId": string "label": string } |
| 字段 | |
|---|---|
联合字段
|
|
buildingId |
可选。建筑物 ID。 |
联合字段
|
|
floorId |
可选。楼层 ID。 |
联合字段
|
|
floorSectionId |
可选。楼层分区 ID。 |
联合字段
|
|
deskId |
可选。桌子 ID。 |
联合字段
|
|
label |
可选。办公地点的直观易懂标签。 |
标签
| JSON 表示法 |
|---|
{ "id": string, "displayName": string, "backgroundColor": string } |
| 字段 | |
|---|---|
id |
仅限输出。唯一标识符。 |
displayName |
可选。显示名称(最多 50 个字符)。 |
backgroundColor |
必需。十六进制格式的背景颜色(例如“#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/calendarhttps://www.googleapis.com/auth/calendar.eventshttps://www.googleapis.com/auth/calendar.events.readonlyhttps://www.googleapis.com/auth/calendar.readonly