用途 本技能是一份分步指南，用于在 Claude Code CLI 中搭建 Google Calendar MCP 服务器，基于 @cocal/google-calendar-mcp（来源：https://github.com/nspady/google-calendar-mcp）。当用户希望把 Google Calendar 连接到 Claude Code 或进行相关设置时使用。
前提条件 需要：已安装 Node.js（用于 npx）、一个 Google 账号、已安装 Claude Code CLI。
第一步：Google Cloud Console 配置 1）创建项目：访问 https://console.cloud.google.com/ ，点击左上角项目下拉菜单 → New Project，名称填 Claude Calendar → Create，然后从下拉菜单选择新项目。 2）启用 Calendar API：进入 APIs & Services → Library，搜索 “Google Calendar API”，点击后启用。 3）OAuth 同意屏幕：进入 APIs & Services → OAuth consent screen，选择 External → Create，填写必填项（App name: Claude Calendar、User support email: 你的邮箱、Developer contact: 你的邮箱），点击 Save and Continue。在 Scopes 页点击 Add or Remove Scopes，添加 https://www.googleapis.com/auth/calendar ，点击 Update → Save and Continue。在 Test Users → Add Users 中添加你的 Gmail → Save and Continue。 4）创建凭据：进入 APIs & Services → Credentials，点击 + Create Credentials → OAuth client ID，Application type 选 Desktop app，Name 填 Claude Code，点击 Create → Download JSON。
第二步：保存凭据 将下载的 JSON 文件保存为： Windows：C:\Users\salmanferoz.google-calendar-mcp\gcp-oauth.keys.json Mac/Linux：~/.google-calendar-mcp/gcp-oauth.keys.json 若 .google-calendar-mcp 文件夹不存在需先创建。
第三步：将 MCP 添加到 Claude Code 自动设置命令（当用户已保存凭据后可自动运行）： Windows：claude mcp add --scope user --transport stdio google-calendar --env GOOGLE_OAUTH_CREDENTIALS="C:\Users\salmanferoz.google-calendar-mcp\gcp-oauth.keys.json" -- npx -y @cocal/google-calendar-mcp Mac/Linux：claude mcp add --scope user --transport stdio google-calendar --env GOOGLE_OAUTH_CREDENTIALS="$HOME/.google-calendar-mcp/gcp-oauth.keys.json" -- npx -y @cocal/google-calendar-mcp 也可手动 JSON 配置，添加到 ~/.claude.json： { "mcpServers": { "google-calendar": { "type": "stdio", "command": "npx", "args": ["-y", "@cocal/google-calendar-mcp"], "env": { "GOOGLE_OAUTH_CREDENTIALS": "/path/to/.google-calendar-mcp/gcp-oauth.keys.json" } } } }
第四步：首次授权 重启 Claude Code：claude。然后提问：“What's on my calendar today?” 浏览器会打开 → 使用 Google 登录 → 点击 Continue（忽略“unverified app”警告）→ 授予日历权限。令牌会自动保存到 .google-calendar-mcp/token.json。
可用工具 list-calendars：枚举可用日历；list-events：按日期筛选检索事件；get-event：按 ID 获取特定事件详情；search-events：按文本查询事件；create-event：新建日历事件；update-event：修改现有事件；delete-event：删除事件；respond-to-event：接受/拒绝/待定邀请；get-freebusy：检查跨日历空闲情况；get-current-time：获取指定时区当前日期/时间；list-colors：查看可用事件颜色；manage-accounts：添加/列出/移除 Google 账号。
功能特性 多账号：连接多个 Google 账号；多日历：一次查询多个日历；冲突检测：查找跨账号的重叠事件；完整 CRUD：创建、读取、更新、删除事件；重复事件：管理重复事件模式；空闲/忙碌：检查跨日历可用性；自然语言：用自然语言安排事件；事件导入：从图片/PDF/网页链接导入事件。
环境变量 GOOGLE_OAUTH_CREDENTIALS：OAuth 凭据文件路径（必填）；GOOGLE_CALENDAR_MCP_TOKEN_PATH：自定义令牌存储位置（可选）。
MCP 管理命令 claude mcp list（列出已配置服务器）；/mcp（在 Claude Code 内检查状态）；claude mcp remove google-calendar（移除服务器）；claude mcp get google-calendar（获取服务器详情）。
故障排查 “Credentials not found”：检查 GOOGLE_OAUTH_CREDENTIALS 路径是否正确；“Access denied”：在 OAuth 同意屏幕中把你的邮箱添加为测试用户；“API not enabled”：在 Cloud Console 中启用 Google Calendar API；令牌过期：删除 token.json 并重新授权；需要每周重新授权：在 Cloud Console 中将应用发布为生产模式。
文件位置摘要 gcp-oauth.keys.json：OAuth 凭据，位于 ~/.google-calendar-mcp/；token.json：认证令牌（自动创建），位于 ~/.google-calendar-mcp/；~/.claude.json：Claude Code 配置，位于用户主目录。