Google Calendar MCP Server

Google 日历 MCP 服务器

这是一个模型上下文协议 (MCP) 服务器，提供与 Google 日历的集成。它允许 LLM 通过标准化接口读取、创建和管理日历事件。

特征

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

要求

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

项目结构

Google Cloud 设置

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

安装

1. 克隆存储库
2. 安装依赖项：
   npm install
3. 构建 TypeScript 代码：
   npm run build
4. 从 Google Cloud Console（在“凭据”下）下载您的 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 服务器：
   npm start
3. 如果没有找到有效的身份验证令牌，服务器将自动：
   • 启动身份验证服务器（在端口 3000-3004 上）
   • 打开浏览器窗口以查看 OAuth 流程
   • 身份验证后安全保存令牌
   • 关闭身份验证服务器
   • 继续正常的 MCP 服务器运行

服务器在需要时自动管理令牌刷新和重新认证：

• 令牌在到期前自动刷新
• 如果刷新失败，清晰的错误消息将指导您重新进行身份验证
• 令牌文件以受限权限安全存储

手动身份验证

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

这将：

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 ：
   { "mcpServers": { "google-calendar": { "command": "node", "args": ["path/to/build/index.js"] } } }
2. 重启Claude桌面

示例用法

除了日历集成所具有的常规功能外，您还可以执行真正动态的操作，例如从屏幕截图和图像添加事件等等。

1. 从屏幕截图和图像添加事件：
   Add this event to my calendar based on the attached screenshot.
   支持的图像格式：PNG、JPEG、GIF 图像可以包含事件详细信息，如日期、时间、地点和描述
2. 检查出勤情况：
   Which events tomorrow have attendees who have not accepted the invitation?
3. 自动协调事件：
   Here's some available that was provided to me by someone I am interviewing. Take a look at the available times and create an event for me to interview them that is free on my work calendar.
4. 提供您自己的可用性：
   Please provide availability looking at both my personal and work calendar for this upcoming week. Choose times that work well for normal working hours on the East Coast. Meeting time is 1 hour

发展

故障排除

常见问题及解决方案：

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 凭据或令牌文件提交到版本控制
• 对于生产用途，请让 Google 验证您的 OAuth 应用程序

执照

麻省理工学院