Google Calendar MCP

Google Calendar MCP

简体中文 | Русский

A1 Google Calendar MCP 让 AI 应用能够通过自然语言管理 Google Calendar。查看本周安排、与来宾一起安排会议并添加 Google Meet 链接、改期或取消会议、查找所有人都有空的时段，以及设置外出办公或专注时间。

它通过你的 Google 账号使用 Google Calendar API。它能够区分整个重复系列和单次日程，并明确说明 Calendar API 的限制，而不会暗示所有日历任务都能完成。

• 19 个工具。 查看日历、活动和空闲/忙碌状态，创建和编辑活动，展开重复系列，以及设置外出办公和专注时间——另有 6 个工具用于连接 Google 账号。
• 直接从聊天中登录。 无需手动编写凭据文件：让助手连接账号，在浏览器中批准访问，下一条请求即可生效——无需重启。客户端密钥以文件路径形式传递，绝不会经过对话。
• 绝不会意外给任何人发邮件。 Calendar API 默认不会发送邀请、变更和取消通知；只有通过 send_updates 明确要求时，才会给来宾发送邮件。
• 绝不重放写入操作。 出现无法确定结果的故障后，服务不会重试写入操作——重复的活动可能会再次给每位来宾发送邮件。
• 仅请求必要的 Google 权限范围。 使用 calendar.events 和 calendar.readonly，不使用权限范围更广的 calendar。

先从一个只读问题开始：

这周我的日历上有什么安排？指出有哪些会议时间重叠。

连接服务 · 探索使用场景 · 查看技术文档

一分钟了解它的工作方式

你： 我周四的安排是什么？我和 Anna 什么时候都有空？

助手： 显示周四的活动以及你们都有空的时段。不会做出任何更改。

你： 在第一个双方都有空的时段，安排一场 45 分钟的设计评审，并添加 Google Meet 链接。

助手： 显示拟定的时间、来宾名单和 Meet 链接，然后在创建活动前请求确认。

你： 确认。

助手： 创建活动。除非你要求发送邀请，否则不会有人收到邮件。

目录

• 快速开始
• 你可以让它做什么
• 活动如何变更
• 可以变更的内容
• 获取访问权限
• 配置
• 数据、限制和后台工作
• 技术文档
• 支持

快速开始

你需要 Node.js 20+、一个 Google 账号，以及来自已启用 Google Calendar API 的 Google Cloud 项目的 OAuth 凭据。

1. 准备 Google OAuth 访问权限。
2. 将服务添加到你的 AI 应用。
3. 提出上面的只读问题。

codex mcp add google-calendar \
  --env GOOGLE_CALENDAR_CLIENT_ID=your_client_id \
  --env GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret \
  --env GOOGLE_CALENDAR_REFRESH_TOKEN=your_refresh_token \
  -- npx -y @a1-x-tech/mcp-google-calendar@latest

codex mcp list

claude mcp add \
  --env GOOGLE_CALENDAR_CLIENT_ID=your_client_id \
  --env GOOGLE_CALENDAR_CLIENT_SECRET=your_client_secret \
  --env GOOGLE_CALENDAR_REFRESH_TOKEN=your_refresh_token \
  --transport stdio --scope user google-calendar \
  -- npx -y @a1-x-tech/mcp-google-calendar@latest

claude mcp list

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "your_client_id",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

{
  "mcpServers": {
    "google-calendar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "your_client_id",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

{
  "servers": {
    "google-calendar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@a1-x-tech/mcp-google-calendar@latest"],
      "env": {
        "GOOGLE_CALENDAR_CLIENT_ID": "${input:calendar_client_id}",
        "GOOGLE_CALENDAR_CLIENT_SECRET": "${input:calendar_client_secret}",
        "GOOGLE_CALENDAR_REFRESH_TOKEN": "${input:calendar_refresh_token}"
      }
    }
  },
  "inputs": [
    { "type": "promptString", "id": "calendar_client_id", "description": "Google OAuth client ID" },
    { "type": "promptString", "id": "calendar_client_secret", "description": "Google OAuth client secret", "password": true },
    { "type": "promptString", "id": "calendar_refresh_token", "description": "Google OAuth refresh token", "password": true }
  ]
}

你可以让它做什么

查看日程

• 我这周有哪些会议？包括周期性会议。
• 显示我明天的一对一会议，以及参会者、Meet 链接和提醒。
• 列出 3 月团队同步会议的所有场次。

安排和更改会议

• 在周四创建一个 45 分钟的评审会议，邀请两位参会者并添加 Google Meet 链接。
• 将复盘会议改期到一小时后，并更新参会者名单——但先不要给任何人发邮件。
• 将规划活动移到团队日历。
• 取消周五的站会，但保留系列中的其他场次。

保护你的时间

• 下周 Anna、Boris 和我什么时候都有一小时空闲？
• 为我的假期设置“外出办公”，并自动拒绝新的邀请。
• 明天上午创建两小时的专注时间，并将 Google Chat 设为静音。

事件变更方式

1. calendar_id: "primary" 是你的主日历；其他日历可通过 list_calendars 获取，写入需要拥有写入权限。
2. 循环系列和单个实例的 ID 不同：系列 ID 会更改或取消所有实例，而实例 ID（来自 list_event_instances）只更改或取消一个实例。
3. update_event 只更改你提供的字段，但嵌套对象会整体替换原对象——新的 attendees 列表会替换整个访客列表。
4. 只有 send_updates 指定发送时，写入操作才会向任何人发送邮件——Calendar API 默认不发送邮件。

外出办公和专注时间块只存在于 Google Workspace 账号的主日历中；个人 Gmail 账号和辅助日历会拒绝这些操作。创建事件不会检查冲突——请先请求空闲/忙碌状态检查。全天事件的结束日期为不包含在内的日期：持续到星期五的事件会在星期六的日期结束。

可以进行的变更

AI 客户端控制确认提示。服务会标记读取、写入和破坏性工具，以便客户端区分查看操作和实际变更。

获取访问权限

访问你自己的日历需要 OAuth 2.0；API 密钥并不足够。有两种连接方式，第一种完全不需要配置文件。

从聊天中登录

不提供凭据启动服务，然后让助手连接。它会通过六个内置工具引导你完成操作：

登录会立即生效：下一次工具调用即可使用，无需重启 AI 客户端。令牌存储在 ~/.config/mcp-google-calendar/credentials.json 中（Windows 系统下位于 %APPDATA%），只有你的账号可以读取，并且绝不会离开你的计算机。

或配置环境变量

经典方式，也是 CI 和无头安装应采用的方式：

1. 创建或选择一个 Google Cloud 项目，并启用 Google Calendar API。

2. 配置 OAuth 同意屏幕，并创建一个 Desktop app OAuth 客户端。

3. 授权要管理其日历的 Google 账号。启用 Use your own OAuth credentials 后，可使用 OAuth 2.0 Playground 获取刷新令牌。

4. 请求以下两个范围：

   https://www.googleapis.com/auth/calendar.events
   https://www.googleapis.com/auth/calendar.readonly
   

   仅当 raw_request 调用需要自行管理日历或共享规则时，才需要较宽泛的 https://www.googleapis.com/auth/calendar 范围。

环境变量始终优先于在聊天中进行的登录，因此已配置的安装会保持原有行为。

测试模式下的 OAuth 刷新令牌可能会在七天后过期。需要长期访问时，请发布 OAuth 应用，或在 Workspace 域中使用 Internal 应用。请将客户端密钥和刷新令牌视为密码。

配置

* 提供 OAuth 三项凭据或访问令牌即可。没有凭据时，服务仍会启动并完成 MCP 握手；首次调用工具时会列出需要设置的确切变量。

数据、限制与后台工作

• 请求会发送至 Google Calendar。 本地服务会刷新 Google OAuth 令牌并调用 Calendar API。其匿名遥测信息包括安装 ID、软件包版本、AI 客户端和平台版本以及工具名称，不包括 OAuth 令牌、日历数据、工具参数或提示词。设置 ASKADS_TELEMETRY=0 即可选择退出。
• Google 会对每个项目实施配额限制。 遇到 429 时，服务会采用退避策略重试；读取操作在网络错误和 5xx 错误后也会重试，而写入操作在结果不确定的失败后不会重放——重复事件可能会再次向每位受邀者发送邮件。
• 没有后台轮询。 服务仅在被调用时运行。list_events 支持通过 updated_min 进行增量检查；如果你的 AI 应用支持计划任务，可以定期检查日历。

技术文档

• MCP 能力目录 — 面向任务的工具说明页面。
• 所有工具和输入
• 开发文档
• 发布文档
• Google Calendar API 参考

支持

发现错误或需要某个使用场景？创建 issue 或在 Telegram 上留言。

你已经读到最后了！