日历集成服务

Google日历MCP服务器

一个模型上下文协议（MCP）服务器，为像Claude这样的AI助手提供Google日历集成功能。

特点

• 多日历支持同时列出多个日历中的事件
• 活动管理创建、更新、删除和搜索日历事件
• 周期性事件针对重复事件的高级修改功能
• 空闲/忙碌查询检查各日历中的可用性
• 智能调度日期和时间的自然语言理解
• 智能进口从图片、PDF 或网页链接中添加日历事件

快速入门

先决条件

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

Google Cloud 设置

1. 前往 Google Cloud 控制台
2. 创建一个新项目或选择一个现有项目。
3. 启用 谷歌日历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桌面配置中添加：

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

查看 Docker 部署指南 包括HTTP传输模式在内的详细配置选项。

首次运行

1. 启动Claude桌面版
2. 首次使用时，服务器将提示进行身份验证
3. 在您的浏览器中完成OAuth流程
4. 你已经准备好使用日历功能了！

重新认证

如果您处于测试模式（默认设置），令牌将在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 Console → “APIs 与服务” → “OAuth 同意屏幕”
2. 点击“发布应用”并确认
3. 您的令牌将不再在7天后过期，但当连接到应用程序时，Google 会显示一条更具威胁性的警告，提示该令牌未经过验证。

见 认证指南 详情见下。

示例用法

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

1. 跨日历可用性：

   复制

   Please provide availability looking at both my personal and work calendar for this upcoming week.
   I am looking for a good time to meet with someone in London for 1 hr.
   

2. 从截图、图片和其他数据源添加事件：

   复制

   Add this event to my calendar based on the attached screenshot.
   

   支持的图像格式：PNG、JPEG、GIF 图片中可以包含事件的详细信息，如日期、时间、地点和描述

3. 日历分析：

   复制

   What events do I have coming up this week that aren't part of my usual routine?
   

4. 检查出勤情况：

   复制

   Which events tomorrow have attendees who have not accepted the invitation?
   

5. 自动协调事件：

   复制

   Here's some available that was provided to me by someone. {available times}
   Take a look at the times provided and let me know which ones are open on my calendar.
   

可用工具

| 列出可用的事件颜色 |

• 文档 身份验证设置
• - 详细的Google Cloud设置 高级用法
• - 多账户，批量操作 部署指南
• - HTTP传输，远程访问 Docker 指南
• - 使用stdio和HTTP模式的Docker部署 OAuth 验证
• - 从测试模式切换到生产模式 建筑学
• - 技术架构概述 发展
• - 贡献与测试 测试

- 单元测试和集成测试指南

配置

• GOOGLE_OAUTH_CREDENTIALS 环境变量：
• GOOGLE_CALENDAR_MCP_TOKEN_PATH - OAuth凭据文件的路径

- 自定义令牌存储位置（可选）

• Claude 桌面配置位置： ~/Library/Application Support/Claude/claude_desktop_config.json
• macOS： %APPDATA%\Claude\claude_desktop_config.json

Windows：

• 安全
• OAuth令牌安全地存储在您系统的配置目录中
• 凭证永远不会离开您的本地机器

所有日历操作均需用户明确同意

1. 故障排除

   • 未找到OAuth凭证文件： 对于npx用户：您 必须 GOOGLE_OAUTH_CREDENTIALS
   • 使用指定凭据文件路径

2. 验证文件路径是否为绝对路径且可访问

   • 认证错误： 确保您的凭证文件中包含一个（用户）的凭证信息 桌面应用程序
   • 类型 验证您的用户电子邮件是否已添加为 测试用户
   • 在Google Cloud OAuth授权屏幕中
   • 尝试删除已保存的令牌并重新进行身份验证

3. 检查是否有其他进程正在占用3000-3004端口

   • 构建错误： npm install && npm run build 跑步
   • 再次
   • 检查 Node.js 版本（建议使用 LTS 版本） build/ 删除该 npm run build

4. 目录并运行

   • 浏览器认证过程中出现“Something went wrong（出了问题）”屏幕
   • 按照以下步骤进行手动验证

5. 使用基于Chromium的浏览器打开认证URL。某些非Chromium浏览器可能不支持测试应用认证。

   • “用户速率限制超出”错误
   • 这种情况通常发生在您的OAuth凭据缺少项目信息时 gcp-oauth.keys.json 确保你的 project_id
   • 文件包含
   • 如需重新下载凭据，请从 Google Cloud Console 中下载 {"installed": {"project_id": "your-project-id", ...}}

文件应具有以下格式：

手动验证

# For npx installations
export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/credentials.json"
npx @cocal/google-calendar-mcp auth

# For local installations
npm run auth

对于重新认证或故障排除：

许可证

麻省理工学院（MIT）

• 支持
• GitHub Issues（GitHub问题）