google-calendar-mcp

google-calendar-mcp

适用于 Google Calendar 的 MCP 服务。单个二进制文件，通过标准输入输出运行，使用用户自己的 Google 账号进行 OAuth 授权。

它回答的是何时——日历、日历上的事件，以及谁有空。会议产生的内容（录音、笔记文档、附件）属于基于 Meet、Docs 和 Drive API 构建的服务。get_event 会列出事件所附文件的名称，并提供这些服务所需的 Drive 文件 ID。

它有何不同

LLM 常用的大多数日历工具，都会在三个细节上出错。本服务围绕避免这些错误而设计，并且每项行为都由测试保证，而不是依赖小心操作：

• 全天事件是日期，不是时间。 它永远不会变成一个确定的时刻，因此不会让 UTC 以西的用户看到日期错位。每个定时事件都带有真实的 IANA 时区，而不只是偏移量，因为偏移量无法跨越夏令时切换展开重复事件。
• 每次读取都会说明读取了什么。 包括绝对时间范围、时区、时区的来源，以及列表是否被截断。如果日程没有说明显示的是哪一个星期四，人们就可能把它误读成任何一个星期四。
• 可用情况不等于事件列表。 即使你看不到某个事件的详情，它仍会让参与者处于忙碌状态；而标记为“空闲”的事件则不会。无法读取的日历会报告为未知，绝不会被归入“空闲”。

设计、证据日志和阶段计划见 docs/architecture.md。

状态

功能已完成并投入使用：读取、写入、重复规则、可用情况、日历、共享、资源和 Claude Desktop 配置包。下方列出了工具；阶段计划和仍待完成的事项见 docs/architecture.md §16。

安装

go install github.com/mmedum/google-calendar-mcp/v5/cmd/google-calendar-mcp@latest

也可以从发布页面下载压缩包。

设置

你需要自己的 Google Cloud 项目和 OAuth 客户端。本仓库不包含任何特定于部署环境的配置。

1. 创建项目并启用 Google Calendar API。
2. 配置 OAuth 同意屏幕，并添加 docs/gcp-setup.md 列出的作用域。该文件由代码生成，因此不会落后于工具功能。
3. 创建类型为 Desktop app 的 OAuth 客户端并下载 JSON 文件。
4. 登录：

google-calendar-mcp login --client-secret ~/path/to/client_secret.json
google-calendar-mcp doctor

doctor 会检查客户端 JSON、已存储的令牌、已授予的作用域以及 API 是否有响应，并说明缺少的内容。

通过 SSH 登录

OAuth 回调会连接到运行 login 的机器的环回接口，而浏览器则在你自己的机器上。请先转发端口。使用 --no-browser：它会打印授权 URL 和需要运行的准确 ssh -L 命令，其中包含实际选用的端口。

配置 MCP 客户端

{
  "mcpServers": {
    "google-calendar": {
      "command": "google-calendar-mcp",
      "env": {
        "GCAL_CLIENT_SECRET": "/path/to/client_secret.json"
      }
    }
  }
}

所有设置均见 docs/configuration.md。

Claude Desktop

每个发行版还包含一个 .mcpb 捆绑包。打开后，Claude Desktop 会安装 MCP 服务，并询问客户端配置中会包含的设置：你的 OAuth 客户端 JSON（可以留空，以使用已记录的那一次 login）、配置文件、只读模式和三个开关。删除日历或其中的所有活动、发布日历并在组织外共享（enable_destructive），以及自动拒绝与其时间重叠的所有会议的活动（enable_decline_all），默认均处于关闭状态，除非你主动开启。在组织内共享（sharing）默认处于开启状态，与手动配置的服务相同；只读模式则不会启用任何需要注册的开关。此服务调用工具前不会征求任何人的许可。Claude Desktop 会逐个审批工具，你可以选择“允许一次”或“始终允许”；选择“始终允许”后，该工具便会在无需再次询问的情况下运行，因此除非需要使用相应工具，否则请保持开关关闭。

该捆绑包支持 macOS、Windows 和 Linux 的两种架构：macOS 使用通用二进制文件，Windows 使用 amd64，Linux 则使用一个在启动时选择相应二进制文件的小型启动器。它不会为你登录。请同时安装二进制文件，并运行一次 google-calendar-mcp login；捆绑包会使用同一登录信息。

工具

工具	功能
list_calendars	列出此账号可查看的所有日历，包括 ID、时区和你的访问级别。从这里开始。
get_calendar	获取某个日历的完整信息，包括与谁共享以及默认提醒。
list_events	在指定时间范围内列出一个或多个日历上的事件，或只列出你指定的类型，例如不在办公室，或邀请邮件所涉及的事件。
search_events	在指定时间范围内进行全文搜索，搜索标题、描述、地点和受邀者。
get_event	获取某个事件的信息，包括受邀者及其回复、受邀者可以执行的操作、你的提醒，以及附加到事件的文件。
list_instances	列出某个重复事件的各次发生记录，包括更改过日期或已移除的记录。
list_changes	查看自上次查看以来的更改，包括删除——列表无法报告删除，因为事件删除后就不再符合筛选条件。返回一个同步令牌，供下次传入；也可以读取自你指定时间点以来的更改。
check_availability	通过 Google 的空闲/忙碌服务查看人们何时忙碌、何时有空，而非根据事件列表判断。可选提供工作时间掩码。
get_settings	获取账号的时区、每周起始日和调色板。
create_event	创建一次性或重复事件，可设置受邀者、可选受邀者、会议室、提醒、可见性、受邀者可执行的操作，并可按需添加 Google Meet 链接。也可在主日历上创建状态事件：不在办公室、专注时间或工作地点。
create_event_declining_all	创建不在办公室或专注时间事件，并拒绝与其时间重叠的所有会议，包括已接受的会议。需启用专属标志。
update_event	更改事件，包括提醒、可见性和受邀者可执行的操作，或添加 Google Meet 链接。只会更改你传入的字段。
cancel_event	取消某个事件，或取消重复事件中的一次发生记录。
move_event	将事件移至另一个日历，这会更改其组织者。
respond_to_event	回复邀请：接受、拒绝或暂定。
create_calendar	创建自己的日历。
manage_calendar	重命名日历或更改其时区、设置你自己的颜色和名称，或将其从你的列表中添加或移除。
list_sharing	查看谁可以查看某个日历，以及每个人可以查看哪些内容。
share_calendar	授予组织内的个人或群组低于所有者级别的访问权限，或更改其现有访问权限。
unshare_calendar	撤销某人的访问权限。
publish_calendar	将日历发布到互联网，或向整个网域开放。需启用相应权限。
widen_calendar_access	与组织外的人员共享，或将某人设为所有者。需启用相应权限。
delete_calendar	删除日历及其上的所有事件。需启用相应权限。
clear_calendar	删除主日历上的所有事件。需启用相应权限。

GCAL_READ_ONLY=true 会注册前九个工具，并且只请求读取范围，因此 API 本身会拒绝写入操作。

manage_calendar 涵盖了 API 分散在两个资源中、而用户通常不会区分的内容：日历——其标题、描述、地点和时区——是所有与其共享的人都能看到的；而你对日历的订阅——颜色、你为它设置的名称、它是否隐藏、你会收到哪些邮件——只属于你自己。取消订阅会将其从你的列表中移除；这不会删除任何内容，也不会让其他人察觉。

每次写入操作都遵循三条规则，每条规则的存在都是因为受调查的服务端会擅自猜测：

• 只要写入操作可能影响到其他人，就必须指定 notify，且两个方向都没有默认值。若访客不属于你的组织，系统会直接拒绝 none——这类访客可能没有可显示该活动的 Google Calendar，因此电子邮件是他们获知活动的唯一方式。
• 重复活动必须指定 scope：instance、series 或 this_and_following。“把每日站会改到 10:30”对应三种不同的操作，但 API 会将它们呈现为同一种操作。
• 每次写入都是受 If-Match 保护的补丁，因此如果有人先一步修改了内容，写入会以 [stale] 拒绝，而不会覆盖对方的修改。添加访客时会先读取访客列表，再将访客添加进去；绝不会替换整个列表。

对其中任意操作设置 dry_run: true，即可查看会有哪些变更，以及会向多少位访客发送电子邮件，而不会实际写入。

访客人数超过 200 时，Google 会停止传播个人回复，因此关于此类活动的每个结果都会说明所列 RSVP 并不完整。

资源

对于附加上下文而非调用工具的客户端，相同内容会以三种资源的形式发布：

URI	内容
gcal://calendars	日历列表，与 list_calendars 返回的内容相同。
gcal://calendars/{calendar_id}	单个日历，与 get_calendar 返回的内容相同。
gcal://calendars/{calendar_id}/events/{event_id}	单个活动，与 get_event 返回的内容相同。

这些资源不包含句柄，也不接受任何参数，因此没有用于日程安排的资源：此处必须指定时间窗口和时区，而 URI 无处填写这两项，若要提供此类 URI，就必须自行臆造两者。

工作时间

check_availability 会在一个时间窗口内查询，而时间窗口只有一个连续区间——因此无法用一次查询询问“下周每天 09:00 到 17:00”。此外，结果中的最长空档是横跨夜间的 15 小时区间，会通过任意 min_minutes。working_from、working_to 和 working_days 则会将空闲时段限制在工作周内。它们没有默认值：若不指定，时间窗口内的每个小时都会计入，结果也总会说明使用了哪些设置。限制会按天应用于结果所呈现的时区，并以当地日期为准，因此在时钟调整的那个星期日，09:00 仍是 09:00。

会议链接

create_event 接受 conference: true，并请求 Google 创建 Google Meet 链接。通常链接会随活动一并返回；但 Google 文档说明，会议链接是异步生成的，因此结果也可能提示链接仍在生成，届时需要重新读取活动。无论哪种情况，结果都会说明链接的状态，并且绝不会报告尚未获得的链接。update_event 接受 add_conference，可为尚无会议链接的活动添加链接。

安全

• 除非设置 GCAL_ENABLE_DESTRUCTIVE=true，否则不会注册两个会删除 Calendar 无法恢复内容的工具——delete_calendar 和 clear_calendar，也不会注册两个扩大日历可见范围的工具——publish_calendar 和 widen_calendar_access；调用每个工具时仍需设置 confirm: true。这两个共享工具还要求提供 list_calendars 显示的日历标题，因此调用中会明确指出要开放哪个日历。cancel_event 则有意不受该标志限制：取消会议是日历的用途之一，Google 会保留记录，而人人都会开启的门槛保护不了任何人。docs/architecture.md §9 对此有论证。取而代之的保护措施是必填的 scope 和 notify。
• 如果取消时设置 notify: none，会议会从你的日历中移除，但仍会保留在受邀者的日历中。结果每次都会说明这一点。
• 共享是这里唯一会让影响超出你账号范围的操作，因此所有共享工具都像其他写入操作一样要求设置 notify——而在这里，Google 的默认设置是发送电子邮件，这与其对事件的默认设置相反。share_calendar 面向你所在组织内的指定个人和群组，权限级别低于所有者：如果某个地址的域名与你账号所属域名相同，它就在组织内；个人 Google 账号没有组织，因此所有地址都在组织之外。向“任何人”或整个域名开放日历属于 publish_calendar；在组织外共享或授予所有者权限属于 widen_calendar_access；share_calendar 仍会降低已获得该日历共享权限的任何人的权限。之后移除公开规则只能阻止新访问者，无法收回已查看过日历的人所获取的信息。移除访问权限时不会通知任何人，因为 Google 不提供请求通知的方式：对方不会收到通知，只会发现日历不见了。
• 设置 GCAL_SHARING=off 会彻底移除所有共享工具，包括权限范围更广的工具。
• 外出或专注时间事件如果拒绝所有与其时间重叠的会议（包括你已经接受的会议），会通知每位组织者，而且删除该事件也无法撤回通知。create_event 会拒绝 auto_decline: all；create_event_declining_all 则会创建此类事件，并且只有设置专用标志 GCAL_ENABLE_DECLINE_ALL=true 后才会注册，因此启用它不会连带启用其他功能。
• 日志会记录方法、工具、结果、耗时和截断后的日历 ID。绝不记录电子邮件地址、事件标题、描述、地点或搜索词。日志在设计上就可以安全地粘贴到错误报告中。

你的 MCP 客户端会批准每次调用；服务端不会主动向你请求批准。claude.ai 和 Codex 会提示你批准标记为破坏性的工具调用：cancel_event、create_event_declining_all、publish_calendar、widen_calendar_access、delete_calendar 和 clear_calendar。VS Code 会提示你批准所有未标记为只读的工具，也就是所有会写入数据的工具。在 Claude Code 中，无论你的规则如何设置，delete_calendar、clear_calendar 和 publish_calendar 每次调用都会请求批准：前两个会删除整个日历中的事件，而 Calendar 无法恢复这些事件；第三个会向互联网或某个域名开放日历，之后移除规则也无法撤回。对于 -p 等无法请求批准的情况，Claude Code 会拒绝执行这些操作。对于其余操作，请在设置的 permissions.ask 下逐条列出你要批准的调用，并将 google-calendar 替换为你为服务端设置的名称。例如，以下写入操作会共享、取消、移动、拒绝或删除：

{
  "permissions": {
    "ask": [
      "mcp__google-calendar__share_calendar", "mcp__google-calendar__unshare_calendar",
      "mcp__google-calendar__publish_calendar", "mcp__google-calendar__widen_calendar_access",
      "mcp__google-calendar__cancel_event", "mcp__google-calendar__move_event",
      "mcp__google-calendar__create_event_declining_all",
      "mcp__google-calendar__delete_calendar", "mcp__google-calendar__clear_calendar"
    ]
  }
}

开发

make check 会运行 CI 中的所有检查，而 make parity 会验证这两份检查列表是否一致。请参阅 CONTRIBUTING.md。

有两项操作需要手动运行，而非由 CI 执行，因为它们会访问此仓库之外的内容。make live 会使用真实账户运行构建好的二进制程序，并在临时日历上执行操作，之后删除该日历。make evals 会评估模型能否通过这些工具，在内存日历中完成 docs/architecture.md §3 中的三项任务，并且需要 ANTHROPIC_API_KEY； go run -tags=evals ./scripts/evals -self-check 则无需密钥或模型即可测试评估框架。

许可证

Apache 2.0。请参阅 LICENSE。