Google 日历 MCP 服务器

一个模型上下文协议 (MCP) 服务器，为 Claude 等 AI 助手提供 Google 日历集成。

特性

• 多账户支持：连接多个 Google 账户（例如工作、个人），并可同时查询它们
• 多日历支持：在单个请求中列出多个日历中的事件
• 跨账户冲突检测：检测任意日历组合之间的重叠事件
• 事件管理：创建、更新、删除和搜索日历事件
• 重复事件：对重复事件提供高级修改功能
• 空闲/忙碌查询：跨日历检查可用性
• 智能排程：自然语言理解日期和时间
• 智能导入：从图片、PDF 或网页链接中添加日历事件

快速入门

前提条件

1. 一个已启用日历 API 的 Google Cloud 项目
2. OAuth 2.0 凭证（桌面应用类型）

Google Cloud 设置

1. 前往 Google Cloud 控制台
2. 创建新项目或选择现有项目。
3. 为您的项目启用 Google 日历 API。在启用 API 之前，请确保顶部栏中选择了正确的项目。
4. 创建 OAuth 2.0 凭证：
   • 转到“凭据”
   • 单击“创建凭据” > “OAuth 客户端 ID”
   • 为应用将访问的数据类型选择“用户数据”
   • 添加您的应用名称和联系信息
   • 添加以下范围（可选）：
     • https://www.googleapis.com/auth/calendar.events 和 https://www.googleapis.com/auth/calendar
   • 将应用类型选择为“桌面应用”（重要！）
   • 保存授权密钥，您需要在下一步中将其路径添加到 JSON 文件中
   • 在 受众界面 下将您的电子邮件地址添加为测试用户
     • 注意：可能需要几分钟才能添加测试用户。在测试用户生效之前，OAuth 同意流程将无法继续。
     • 关于测试模式的说明：当应用处于测试模式时，授权令牌将在 1 周后过期，需要重新认证（请参阅下方的“重新认证”部分）。

安装

选项 1：使用 npx（推荐）

将以下内容添加到您的 Claude Desktop 配置中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}

⚠️ 使用 npx 的重要提示：使用 npx 时，您必须通过 GOOGLE_OAUTH_CREDENTIALS 环境变量指定凭证文件路径。

选项 2：本地安装

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

然后将本地路径添加到 Claude Desktop 配置中，或者通过 GOOGLE_OAUTH_CREDENTIALS 环境变量指定路径。

选项 3：Docker 安装

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up

有关详细配置选项（包括 HTTP 传输模式），请参阅 Docker 部署指南。

首次运行

1. 启动 Claude Desktop
2. 让 Claude 认证 Google 日历 MCP 服务器（例如，“认证 Google 日历”）。这是使用任何日历工具之前必需的步骤——如果没有这一步，请求将返回 -32600 错误。
3. 在浏览器中完成 OAuth 流程
4. 您现在可以使用日历功能了！

使用 Claude Code？ 步骤相同——只需在 CLI 会话中让 Claude 先认证 Google 日历 MCP 服务器，然后再使用任何日历工具。

反复认证

如果您处于默认的测试模式，令牌将在 7 天后过期。如果您使用的是 Claude Desktop 等客户端，它应该会自动打开浏览器窗口进行重新认证。但是，如果出现认证错误，您也可以按照以下步骤解决：

对于 npx 用户：

export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json"
npx @cocal/google-calendar-mcp auth

对于本地安装：

npm run auth

为了避免每周重新认证，您可以将您的应用发布到生产模式（无需验证）：

1. 前往 Google Cloud 控制台 → “API 和服务” → “OAuth 同意屏幕”
2. 单击“发布应用”并确认
3. 您的令牌将不再在 7 天后过期，但 Google 会显示一条关于该应用未经验证的警告。

有关详细信息，请参阅 认证指南。

管理多个账户

连接多个 Google 账户，并可同时使用它们。

在聊天中（推荐）： 使用 manage-accounts 工具直接从您的 AI 助手添加、列出或移除账户——无需终端。有关详细信息，请参阅 认证指南。

CLI： 对于初始设置，使用 npm run account auth <昵称>（例如，npm run account auth work）。

HTTP / Docker： 访问 http://localhost:3000/accounts，即可在浏览器中管理账户。

当工具未提供 account 参数时，只读工具会合并所有账户的结果，而写入工具则会自动选择具有相应权限的账户。

使用示例

除了日历集成应有的常规功能外，您还可以执行非常动态的多步骤流程，例如：

1. 跨日历可用性：

   请查看我本周个人日历和工作日历的空闲时间。
   我想找一个合适的时间与伦敦的朋友会面，时长1小时。
   

2. 添加来自截图、图片及其他数据源的日程：

   根据附件中的截图，将此事件添加到我的日历中。
   

   支持的图片格式：PNG、JPEG、GIF 图片中可以包含日期、时间、地点和描述等事件详情。

3. 日历分析：

   本周有哪些不属于我日常安排的活动？
   

4. 检查参会情况：

   明天有哪些活动的参会者尚未接受邀请？
   

5. 回复邀请：

   接受我日历上明天下午2点的团队会议邀请。
   

   拒绝并附带说明：

   拒绝周五的会议，并注明我有日程冲突。
   

   回复重复性事件：

   只接受本周的站会，但保留未来其他场次为暂定状态。
   

   拒绝所有未来的周一计划会议。
   

6. 自动协调事件：

   这是某人提供给我的一些空闲时间。{可用时间}
   请查看这些时间，并告诉我哪些在我的日历上是空闲的。
   

可用工具

工具	描述
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 Cloud设置
• 高级使用 - 多账号、批量操作
• 部署指南 - HTTP传输、远程访问
• Docker指南 - Docker部署，支持标准输入输出和HTTP模式
• 架构 - 技术架构概述
• 开发 - 贡献与测试
• 测试 - 单元及集成测试指南
• 多账号更新 - 当前状态及多账号支持路线图

赞助

如果Google Calendar MCP对您有所帮助，并且您愿意的话，我将非常感激您能考虑赞助我的开源项目。

谢谢！——内特

配置

环境变量：

• GOOGLE_OAUTH_CREDENTIALS - OAuth凭证文件路径
• GOOGLE_CALENDAR_MCP_TOKEN_PATH - 自定义令牌存储位置（可选）
• ENABLED_TOOLS - 以逗号分隔的启用工具列表（参见下方的工具过滤）

工具过滤

您可以使用--enable-tools标志或ENABLED_TOOLS环境变量来限制向AI助手暴露的工具。这在以下情况下很有用：

• 减少上下文消耗：每个工具都会占用AI上下文窗口中的令牌。限制工具数量有助于为更长时间的对话保留更多上下文。
• 安全性：仅允许只读操作或特定功能。
• 简洁性：只公开您的工作流真正需要的工具。

通过命令行：

npx @cocal/google-calendar-mcp start --enable-tools list-events,create-event,get-current-time

通过Claude Desktop配置中的环境变量：

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/credentials.json",
        "ENABLED_TOOLS": "list-events,create-event,get-current-time,update-event"
      }
    }
  }
}

可用工具名称： list-calendars、list-events、search-events、get-event、list-colors、create-event、update-event、delete-event、get-freebusy、get-current-time、respond-to-event、manage-accounts

注意： 无论是否进行工具过滤，manage-accounts工具始终可用，因为它用于管理身份验证。

当工具过滤启用时，服务器会向AI助手提供指令，列出哪些工具已被禁用。这样，AI可以在不消耗完整工具架构令牌成本的情况下，告知用户存在额外的功能，但目前不可用。

如果列表为空或仅包含逗号，服务器将无法启动，并显示错误信息。

如果指定了无效的工具名称，服务器同样会因显示所有可用工具而启动失败。

安全性

• OAuth令牌安全地存储在您系统的配置目录中
• 凭证永远不会离开您的本地设备
• 所有日历操作都需要用户明确同意

故障排除

1. 未找到OAuth凭证文件：

   • 对于使用npx的用户：必须使用GOOGLE_OAUTH_CREDENTIALS指定凭证文件路径。
   • 确认文件路径为绝对路径且可访问。

2. 认证错误：

   • 确保您的凭证文件包含适用于“桌面应用”类型的凭据。
   • 确认您的用户邮箱已在Google Cloud OAuth同意页面中被添加为“测试用户”。
   • 尝试删除已保存的令牌并重新进行认证。
   • 检查是否有其他进程正在占用3500–3505端口。

3. 构建错误：

   • 再次运行npm install && npm run build。
   • 检查Node.js版本（建议使用LTS版本）。
   • 删除build/目录并重新运行npm run build。

4. 浏览器认证过程中出现“发生错误”界面：

   • 手动运行认证命令（参见上方的“重新认证”部分）。
   • 使用基于Chromium的浏览器。某些非Chromium浏览器可能无法正常完成测试应用认证。

5. “用户速率限制已超过”错误：

   • 这通常发生在您的OAuth凭证缺少项目信息时。
   • 确保您的gcp-oauth.keys.json文件包含project_id。
   • 如有必要，从Google Cloud控制台重新下载凭证。
   • 文件格式应为：{"installed": {"project_id": "your-project-id", ...}}

许可证

MIT

支持

• GitHub问题
• 文档

Google Calendar MCP 快速上手指南

Google Calendar MCP 是一个基于模型上下文协议（MCP）的服务器，旨在为 Claude 等 AI 助手提供强大的 Google 日历集成能力。支持多账号管理、跨日历冲突检测、智能日程安排及从图片/PDF 导入事件等功能。

环境准备

在开始之前，请确保满足以下系统和依赖要求：

1. Node.js 环境：建议安装最新的 LTS 版本。
2. Google Cloud 项目：
   • 拥有一个 Google Cloud 项目。
   • 已启用 Google Calendar API。
3. OAuth 2.0 凭证：
   • 类型必须选择 "Desktop app" (桌面应用)。
   • 需在 OAuth 同意屏幕中将你的邮箱添加为 测试用户 (Test User)（否则无法通过验证）。
   • 下载生成的 JSON 密钥文件（例如 gcp-oauth.keys.json）。

注意：由于网络原因，访问 Google Cloud Console 可能需要特定的网络环境。

安装步骤

推荐使用 npx 方式直接运行，无需克隆代码库。

1. 配置 Claude Desktop

根据你的操作系统，找到并编辑 claude_desktop_config.json 配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

将以下内容添加到配置文件中。请务必将 /path/to/your/gcp-oauth.keys.json 替换为你本地实际的 OAuth 密钥文件绝对路径。

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}

重要提示：使用 npx 运行时，必须通过 GOOGLE_OAUTH_CREDENTIALS 环境变量指定凭证文件的路径，否则无法启动。

2. (可选) 本地安装或 Docker

如果你需要自定义开发或使用 Docker 部署，可参考以下方式：

本地安装：

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

配置时需将 command 改为 node，args 指向构建后的入口文件，并同样配置环境变量。

Docker 安装：

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up

基本使用

配置完成后，按照以下步骤即可开始使用。

第一步：启动与认证

1. 重启 Claude Desktop 应用程序以加载新的 MCP 配置。
2. 在对话框中输入指令触发认证，例如：

   "Authenticate with Google Calendar" （或者中文："请登录 Google 日历"）

3. 系统会自动在浏览器中打开 OAuth 授权页面。
4. 登录你的 Google 账号并允许访问权限。
5. 认证成功后，即可开始使用日历功能。

注意：如果是测试模式（默认），令牌有效期为 7 天。过期后再次请求时，Claude 会自动弹出浏览器窗口引导你重新认证。

第二步：常用指令示例

认证成功后，你可以使用自然语言与 AI 交互，执行复杂的日历操作：

• 查询空闲时间（跨日历）：

  "请查看我的工作和个人日历，找出下周与伦敦同事开会 1 小时的合适时间。"

• 从图片创建事件：

  "根据这张截图中的信息，帮我把活动添加到日历里。" (支持 PNG, JPEG, GIF 格式，AI 会自动识别时间、地点和描述)

• 管理会议邀请：

  "接受明天下午 2 点的团队会议邀请。" "拒绝周五的会议，并回复说我有时间冲突。"

• 分析日程：

  "本周有哪些不属于我常规日程安排的会议？"

可用工具列表

底层支持以下工具供 AI 调用：

工具名称	功能描述
list-calendars	列出所有可用日历
list-events	列出指定日期的事件
create-event	创建新事件
update-event / delete-event	更新或删除事件
get-freebusy	检查跨日历的空闲/忙碌状态
respond-to-event	响应邀请（接受/拒绝/暂定）
manage-accounts	管理多个连接的 Google 账号
search-events	通过文本搜索事件

现在你已经完成了设置，可以开始让 AI 助手帮你高效管理日程了！