Google 日历 MCP 服务器

这是一个 Model Context Protocol (MCP) 服务器，提供了与 Google 日历的集成。它允许 LLMs 通过标准化接口读取、创建和管理日历事件。

功能

• 列出可用的日历
• 从日历中列出事件
• 创建新的日历事件
• 更新现有事件
• 删除事件
• 从截图和图像中处理事件

要求

1. Node.js 16 或更高版本
2. TypeScript 5.3 或更高版本
3. 启用了 Calendar API 的 Google Cloud 项目
4. OAuth 2.0 凭证（客户端 ID 和客户端密钥）

项目结构

google-calendar-mcp/
├── src/ # TypeScript 源文件
├── build/ # 编译后的 JavaScript 输出
├── llm/ # LLM 特定的配置和提示
├── package.json # 项目依赖项和脚本
└── tsconfig.json # TypeScript 配置

Google Cloud 设置

1. 前往 Google Cloud 控制台
2. 创建一个新项目或选择一个现有项目。
3. 为您的项目启用 Google 日历 API。在启用 API 之前，请确保从顶部栏中选择了正确的项目。
4. 创建 OAuth 2.0 凭证：
   • 进入“凭据”
   • 点击“创建凭据” > “OAuth 客户端 ID”
   • 选择“用户数据”作为应用程序将访问的数据类型
   • 添加您的应用名称和联系信息
   • 添加以下范围（可选）：
     • https://www.googleapis.com/auth/calendar.events
   • 选择“桌面应用”作为应用程序类型
   • 在 OAuth 同意屏幕 中添加您的电子邮件地址作为测试用户
     • 注意：添加测试用户需要几分钟时间。在测试用户传播完成之前，OAuth 同意流程不会让您继续进行。

安装

1. 克隆仓库

2. 安装依赖项：
   bash
   npm install

3. 构建 TypeScript 代码：
   bash
   npm run build

4. 从 Google Cloud 控制台下载您的 Google OAuth 凭证（在“凭据”下），并将文件重命名为 gcp-oauth.keys.json 放在项目的根目录中。

可用脚本

• npm run build - 构建 TypeScript 代码
• npm run build:watch - 以监视模式构建 TypeScript 代码，用于开发
• npm run dev - 使用 ts-node 以开发模式启动服务器
• npm run auth - 启动用于 Google OAuth 流程的身份验证服务器

身份验证

服务器支持自动和手动身份验证流程：

自动身份验证（推荐）

1. 将您的 Google OAuth 凭证放在项目根目录中的名为 gcp-oauth.keys.json 的文件中。

2. 启动 MCP 服务器：
   bash
   npm start

3. 如果没有找到有效的身份验证令牌，服务器将自动执行以下操作：

   • 启动身份验证服务器（端口 3000-3004）
   • 打开浏览器窗口进行 OAuth 流程
   • 认证后安全保存令牌
   • 关闭身份验证服务器
   • 继续正常的 MCP 服务器操作

服务器会自动管理令牌刷新和重新认证：

• 令牌在过期前会自动刷新
• 如果刷新失败，清晰的错误消息将引导您完成重新认证
• 令牌文件以受限权限安全存储

手动身份验证

对于高级用户或故障排除，您可以手动运行身份验证流程：
bash
npm run auth

这将：

1. 启动身份验证服务器
2. 打开浏览器窗口进行 OAuth 流程
3. 保存令牌并退出

安全注意事项

• OAuth 凭证存储在 gcp-oauth.keys.json 中
• 身份验证令牌存储在 .gcp-saved-tokens.json 中，权限为 600
• 令牌会在后台自动刷新
• 每次 API 调用前都会验证令牌的完整性- 认证服务器在成功认证后会自动关闭
• 切勿将 OAuth 凭据或令牌文件提交到版本控制系统

用法

服务器提供了以下工具：

• list-calendars: 列出所有可用的日历
• list-events: 从日历中列出事件
• create-event: 创建新的日历事件
• update-event: 更新现有的日历事件
• delete-event: 删除日历事件

与 Claude Desktop 一起使用

1. 将此配置添加到您的 Claude Desktop 配置文件中。例如：/Users/<user>/Library/Application Support/Claude/claude_desktop_config.json:
   json
   {
   "mcpServers": {
   "google-calendar": {
   "command": "node",
   "args": ["path/to/build/index.js"]
   }
   }
   }

2. 重启 Claude Desktop

示例用法

除了您期望的日历集成的常规功能外，您还可以执行一些非常动态的操作，例如从截图和图像中添加事件等。

1. 从截图和图像中添加事件：

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

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

2. 检查出席情况：

   明天哪些事件有未接受邀请的参与者？

3. 自动协调事件：

   这里有一些由我面试的人提供的可用时间。查看这些可用时间，并在我的工作日历中创建一个空闲时间来面试他们。

4. 提供您自己的可用时间：

   请查看我的个人和工作日历，为即将到来的一周提供可用时间。选择适合东海岸正常工作时间的时间。会议时间为1小时。

开发

故障排除

常见问题及解决方案：

1. OAuth 令牌在一周（7天）后过期

   • 处于测试模式而非生产模式的应用程序需要在一周后重新进行 OAuth 流程。

2. OAuth 令牌错误

   • 确保 gcp-oauth.keys.json 格式正确
   • 尝试删除 .gcp-saved-tokens.json 并重新认证

3. TypeScript 构建错误

   • 确保已安装所有依赖项：npm install
   • 检查 Node.js 版本是否符合先决条件
   • 清除构建目录：rm -rf build/

4. 图像处理问题

   • 确认图像格式受支持
   • 确保图像包含清晰可读的文本

安全注意事项

• 服务器本地运行并需要 OAuth 认证
• OAuth 凭据应存储在项目根目录下的 gcp-oauth.keys.json 中
• 认证令牌存储在具有受限文件权限的 .gcp-saved-tokens.json 中
• 令牌在过期时会自动刷新
• 切勿将 OAuth 凭据或令牌文件提交到版本控制系统
• 对于生产用途，请让您的 OAuth 应用程序通过 Google 的验证

许可证

MIT