Google Calendar MCP Server

什么是 Google Calendar MCP Server？

这个 Google Calendar MCP 服务器是 takumi0706 开发的社区 TypeScript 服务器，把 Claude Desktop 连接到 Google Calendar API；通过 Google OAuth2 登录后，Claude 就能用自然语言列出、创建、更新和删除你的日历事件。

它以 @takumi0706/google-calendar-mcp 发布在 npm 上，通过 stdio 在本地运行，采用 MIT 许可证，并非 Google 出品，需要你自备 Google Cloud OAuth 客户端。2.0.0 版本为 OAuth 流程加入了 PKCE，升级到 MCP 协议修订版 2026-07-28（仍兼容 2025 年的旧修订版），并要求 Node.js 20 或更高版本。

如何使用 Google Calendar MCP Server？

前置条件：

1. Node.js 20 或更高版本。
2. 一个已启用 Google Calendar API 的 Google Cloud 项目。
3. 在 Google Cloud Console 中创建的 OAuth2 凭据（client ID 和 client secret）。注册的重定向 URI 必须与 GOOGLE_REDIRECT_URI 一致，README 默认使用 http://localhost:4153/oauth2callback。

环境变量：

• GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET、GOOGLE_REDIRECT_URI（必填）
• TOKEN_ENCRYPTION_KEY（可选，未设置时自动生成；必须恰好为 64 个十六进制字符）
• 本地认证服务器的 AUTH_PORT / AUTH_HOST（默认 4153 / localhost），以及 MCP 服务器的 PORT / HOST（默认 3000 / localhost）
• 无法访问 localhost 时（例如在远程服务器或容器中）设置 USE_MANUAL_AUTH=true

Claude Desktop

在 claude_desktop_config.json 中添加服务器：

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@takumi0706/google-calendar-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:4153/oauth2callback"
      }
    }
  }
}

首次使用时会打开浏览器窗口进行 Google 登录和授权；若设置了 USE_MANUAL_AUTH=true，则改为粘贴 Google 显示的授权码。

其他 MCP 客户端

README 面向的是 Claude Desktop。由于这是标准的 stdio 服务器，Claude Code、Cursor 或 VS Code 可以用相同的 env 值运行同样的 npx -y @takumi0706/google-calendar-mcp 命令，但作者没有为这些客户端编写文档。

全局安装或从源码安装

npm install -g @takumi0706/google-calendar-mcp

git clone https://github.com/takumi0706/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build
npm start

Google Calendar MCP Server 的主要功能

• 完整的事件管理：在主日历或任意其他日历上获取、创建、更新和删除事件。
• 局部更新：updateEvent 会先获取现有事件再合并你的修改，未提及的字段会保留。
• 通过 RFC 5545 规则创建重复事件，例如 RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR。
• 通过 colorId（1 到 11）设置事件颜色，并支持参与者、地点、描述和时区。
• 使用 authenticate 工具无需重启 Claude 即可切换 Google 账号。
• v2 的安全加固：PKCE（S256）、一次性且 10 分钟过期的 CSPRNG state、固定的重定向 URI、Zod 输入校验，以及内存中的 AES-256-GCM 令牌加密。
• 适用于无界面环境的手动认证模式。

Google Calendar MCP Server 工具

服务器提供五个工具：

• 读取：getEvents 列出事件，可选参数有 calendarId、timeMin/timeMax（ISO 8601）、maxResults（默认 10）和 orderBy（startTime 或 updated）。
• 写入：createEvent 接收一个 event 对象，包含 summary、start 和 end（日期时间或全天的 date），以及可选的描述、地点、参与者、colorId 和 recurrence；updateEvent 接收 eventId 以及需要修改的字段。
• 删除：deleteEvent 按 eventId 删除事件。
• 账号：authenticate 重新执行 Google 登录，可在会话中途切换账号。

Google Calendar MCP Server 的使用场景

• 查看日程：“我明天下午有哪些会议？”
• 预约时间：“周五东京时间 10:00 和 alex@example.com 安排一个 30 分钟的通话。”
• 设置例行事项：“每周一、三、五上午 9 点添加团队同步会。”
• 安全地改期：“把我的牙医预约改到下周二同一时间”，事件的其他信息不会丢失。
• 整理日历：“把我本周所有专注时间块改成绿色”，或“删除已取消的设计评审”。
• 通过用另一个 Google 账号重新认证，在个人日历和工作日历之间切换。

Google Calendar MCP Server 与替代方案对比

社区里有很多 Google Calendar MCP 服务器，大多采用相同模式：本地服务器加上你自己的 Google Cloud OAuth 凭据。这个服务器小巧（五个工具）、专注于 Claude Desktop，并且最近做过安全加固。如果你不想管理 Google Cloud 项目，可以改用 Zapier MCP 这类托管连接平台，通过 Zapier 账号提供 Google Calendar 操作。若使用 Microsoft 日历，可参考 Outlook MCP Server。

Google Calendar MCP Server 常见问题排查

• 认证错误：仔细核对 client ID 和 secret，确认已启用 Calendar API，并确保在 Google Cloud 中注册的重定向 URI 与 GOOGLE_REDIRECT_URI 完全一致。
• Authentication failed: Invalid state parameter：升级到 1.0.3 或更高版本；旧版本需要释放 4153 端口后重启。
• 无法访问 localhost：设置 USE_MANUAL_AUTH=true，手动粘贴授权码。
• 空参数导致错误 -32602：升级到 1.0.7 或更高版本，该版本会忽略空字符串、null 和 undefined 值。
• 连接错误或端口冲突：只运行一个服务器实例；从 v2 起，如果端口已被占用，认证服务器会直接中止。