google-calendar

Google Calendar

用于管理 Google Calendar 的工具——创建、读取、更新、移动和删除活动；搜索日历；列出和创建日历；检查忙闲状态；解析活动颜色调色板；以及管理日历共享（ACL）。封装了 Google Calendar API v3（https://www.googleapis.com/calendar/v3/）。通过单个连接使用 OAuth 2.0 进行身份验证——能力取决于授权范围和每个日历的访问角色，而非令牌类型。

面向 Google Calendar 的独立非官方连接器。与 Google Calendar 无关联，也未获其认可或赞助。“Google Calendar”是其所有者的商标，此处仅用于标识本连接器所支持的服务。

适用场景

• Agent 需要安排、查找、重新安排、移动或取消日历活动。
• Agent 需要检查某人在一个或多个日历中的忙闲时间。
• Agent 需要列出或创建日历，或读取日历的默认时区。
• Agent 需要与他人共享日历或撤销访问权限（ACL 管理；需要 owner 角色）。

设置

这是一个 agentskills.io 技能。

如果尚未将连接器安装为技能，请先运行 npx skills add zapier/connectors --skill google-calendar（或使用你自己的运行环境所提供的技能安装机制）进行安装，然后继续操作。安装技能只会复制这些文件，不会安装依赖项。运行 CLI、本地 MCP 服务或 zapier-sdk 身份验证命令之前，请先在此处运行一次 npm install --omit=dev。如果要在自己的项目中将已发布的软件包作为依赖项导入？npm install 已会解析所有依赖项——请参阅 references/use-as-sdk.md。

如果你想获取实际的仓库源码——以便浏览 references/、运行此连接器的测试或修改它，请参阅 README.md，了解如何克隆指定范围的内容。

此连接器需要 Node.js 22.18+。选择与你的运行方式相符的参考文档，并在进行任何其他操作之前先加载它：

你拥有……	加载
支持 MCP 的客户端——工具可能已加载（例如 mcp__google-calendar__<tool>），或者你可以自行注册本地服务（也可以指导用户注册）	references/use-as-mcp.md
终端／子进程访问权限（你可以运行 node）	references/use-as-cli.md
只有你自己的代码，并将此软件包作为依赖项导入	references/use-as-sdk.md
无法使用工具、终端，也无法导入此软件包——你要编写自己的代码，直接调用 Google Calendar API（例如在代码执行沙箱中）	references/use-as-recipe.md

脚本

脚本	脚本名称	连接	描述
scripts/createEvent.ts	createEvent	单个（"google-calendar"）	创建活动（定时/全天、重复、参会者、提醒、颜色、Google Meet）。
scripts/quickAddEvent.ts	quickAddEvent	单个（"google-calendar"）	根据简单文本字符串创建活动——解析标题和日期/时间。
scripts/updateEvent.ts	updateEvent	单个（"google-calendar"）	部分更新活动。数组字段会被替换；如需添加参会者，请使用 addEventAttendees。
scripts/addEventAttendees.ts	addEventAttendees	单个（"google-calendar"）	在不移除现有参会者的情况下向活动添加访客（读取-修改-写入）。
scripts/moveEvent.ts	moveEvent	单个（"google-calendar"）	将活动移至其他日历（仅限默认活动）。
scripts/deleteEvent.ts	deleteEvent	单个（"google-calendar"）	删除活动。幂等——已删除的活动仍会报告成功。
scripts/listEvents.ts	listEvents	单个（"google-calendar"）	按时间范围、文本或活动类型列出/搜索日历中的活动。
scripts/getEvent.ts	getEvent	单个（"google-calendar"）	根据 ID 获取单个活动（例如，读取已解析的 Google Meet 链接）。
scripts/listEventInstances.ts	listEventInstances	单个（"google-calendar"）	列出重复活动的各次发生；解析实例 ID，以便编辑单次活动。
scripts/listCalendars.ts	listCalendars	单个（"google-calendar"）	列出日历及其 ID、访问角色、主日历标记和时区。用于解析主日历 ID。
scripts/getCalendar.ts	getCalendar	单个（"google-calendar"）	获取日历元数据；getCalendar("primary") 会返回用户的默认时区。
scripts/createCalendar.ts	createCalendar	单个（"google-calendar"）	创建新的辅助日历。
scripts/queryFreeBusy.ts	queryFreeBusy	单个（"google-calendar"）	返回一个或多个日历在指定时间范围内的忙碌时段。
scripts/getColors.ts	getColors	单个（"google-calendar"）	返回活动和日历的颜色调色板（colorId 索引 → 十六进制值）。
scripts/listAclRules.ts	listAclRules	单个（"google-calendar"）	列出日历的共享规则。需要 owner 角色。
scripts/createAclRule.ts	createAclRule	单个（"google-calendar"）	以指定角色向用户/群组/网域共享日历（或更改共享的角色）。需要 owner。
scripts/deleteAclRule.ts	deleteAclRule	单个（"google-calendar"）	移除共享规则（撤销访问权限）。需要 owner。
每个脚本文件中的 inputSchema / outputSchema（Zod）是其契约的权威来源。

歧义处理与拒绝

• 先确认，再操作。 创建、移动或分享日历或事件之前，如果目标是按名称查找的，先确认目标。通过 listCalendars 按名称查找日历时，统计 summary 完全匹配（不区分大小写）的数量：恰好一个 → 对其操作；两个或更多匹配 → 停止，列出候选项及其 id + accessRole，并询问用户选择哪一个。通过 listEvents 查找的事件也适用此规则（一个人可能有多个同名事件）；通过 listAclRules 查找的 ACL 规则同样适用。绝不要默默选择第一项匹配。
• 不要伪造不支持的操作。 此连接器不支持重命名或删除日历、清除日历中的所有事件（calendars.clear）、导入外部来源的事件（events.import）、在一次调用中执行“此项及后续项”的重复事件编辑，或设置触发器/通知（监视频道）。如果用户要求执行其中任何一项，请说明不支持并停止——不要用其他工具代替（例如逐个删除事件来模拟“清除日历”，或修改主事件来伪装“此项及后续项”），也不要谎称已成功执行未实际完成的操作。对于单个重复事件实例，请使用 listEventInstances → 对该实例的 id 调用 updateEvent。

身份验证

每种形态都通过一个连接选择器传递身份验证信息，而非密钥——格式为 [<resolver>:]<value>。每个连接器都接受 zapier:<connection-id>（由 Zapier 管理的身份验证——通过 Zapier 的身份验证、重试和治理层）；有些连接器还接受一个或多个直接令牌解析器（名称和数量因连接器而异）——请检查此连接器自身支持的解析器，不要想当然。<resolver>: 前缀是可选的；裸值会交给第一个能识别它的解析器——UUID 格式的裸值始终会被 zapier: 识别。每个脚本都会声明所需的连接以及其接受的解析器。传递连接的确切语法（以及如何查看此连接器的解析器列表）因形态而异——请参阅上文加载的参考文档。

想先检查已配置的内容？不要为此导出环境变量值——env 或 env | grep <name> 会同时打印名称和值；如果设置了值，就会将有效凭据泄露到对话记录中。只检查名称（env | cut -d= -f1 | grep -i <name>），或直接测试已知名称（[ -n "$VAR_NAME" ]）。

还没有连接？选择一种方式，并按照相应参考文档中的流程获取连接；切勿直接向用户索要连接 id 或令牌，仿佛他们早已记得：

	加载
直接传递凭据	references/use-without-zapier.md
通过 Zapier 连接路由	references/use-with-zapier.md

输出格式

每个脚本都会返回一个 { data, meta } 信封：

• data — 脚本的结果（其形状由 outputSchema 声明；有关如何在你的 shape 中检查脚本的确切 schema，请参阅上文加载的参考文档）。
• meta.outputDataValidation — 对 data 进行验证的结果：
  • { skipped: false, droppedPaths: null } — 已验证，没有移除任何内容。
  • { skipped: false, droppedPaths: [...], instruction } — 已验证，但这些路径已从 data 中剥离：这些字段是脚本从 API 返回、但 outputSchema 未声明的字段。如果需要这些字段，请重新运行并跳过输出验证。
  • { skipped: true } — 已绕过验证；data 是未经检查的脚本原始输出。

读取已剥离字段 / skipOutputDataValidation。 如需接收未经验证的原始结果，可选择跳过输出验证（具体语法因 shape 而异，请参阅上文加载的参考文档）。输入验证绝不会跳过。

精简结果 / filterOutputData。 如需将大型结果缩减为所需字段，请传入一个对 data 进行后处理的 jq 表达式（具体语法同样取决于 shape）。jq 只针对 data 运行，不会处理 { data, meta } 信封，因此表达式应以 data 为根（运行脚本的 --help，或 shape 的等效命令，查看其输出 schema）。转换后的值会替换 data，meta 保持不变，并且结果不会根据输出 schema 重新验证。

参考文档

在对应领域操作前，先加载匹配的参考文件：

参考文档	涵盖内容	加载时机
google-calendar-api-gotchas.md	错误信封及恢复方法、全天事件的排他性 end.date、周期性事件必需的 timeZone、事件类型创建限制、异步创建 Meet、分页上限、每个日历的空闲/忙碌错误，以及 ACL 所有者角色规则。	在构建事件日期/时间、周期性事件、颜色或 Google Meet 链接之前；处理 401/403/404/410 错误时；更新事件时（数组字段会被整体替换）；或共享日历（ACL）时。