Google 日历 MCP 服务器

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

示例用法

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

1. 从屏幕截图和图像添加事件：
   Add this event to my calendar based on the attached screenshot.
   支持的图像格式：PNG、JPEG、GIF 图像可以包含事件详细信息，如日期、时间、地点和描述
2. 日历分析：
   What events do I have coming up this week that aren't part of my usual routine?
3. 检查出勤情况：
   Which events tomorrow have attendees who have not accepted the invitation?
4. 自动协调事件：
   Here's some available that was provided to me by someone. Take a look at the available times and create an event that is free on my work calendar.
5. 提供您自己的可用性：
   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. Node.js（推荐使用最新 LTS）
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 （或更广泛的https://www.googleapis.com/auth/calendar如果需要）
   • 选择“桌面应用程序”作为应用程序类型（重要！）
   • 在OAuth 同意屏幕下将您的电子邮件地址添加为测试用户
     • 注意：添加测试用户需要几分钟时间。在测试用户传播之前，OAuth 同意不允许您继续操作。
     • 关于测试模式的注意事项：当应用程序处于测试模式时，身份验证令牌将在 1 周后过期，需要通过运行npm run auth进行刷新。

安装

1. 克隆存储库
2. 安装依赖项（这也通过 postinstall 构建 js）：
   npm install
3. 从 Google Cloud Console（在“凭据”下）下载您的 Google OAuth 凭据，并将文件重命名为gcp-oauth.keys.json并将其放在项目的根目录中。
   • 确保该文件包含“桌面应用程序”的凭据。
   • 或者，复制提供的模板文件： cp gcp-oauth.keys.example.json gcp-oauth.keys.json并使用来自 Google Cloud Console 的凭据填充它。

可用脚本

• npm run build - 构建 TypeScript 代码（编译src以build ）
• npm run typecheck - 无需编译即可运行 TypeScript 类型检查
• npm run start - 启动已编译的 MCP 服务器（使用node build/index.js ）
• npm run auth - 手动运行 Google OAuth 身份验证流程。
• npm test - 使用 Vitest 运行单元/集成测试套件
• npm run test:watch - 在监视模式下运行测试
• npm run coverage - 运行测试并生成覆盖率报告

验证

服务器处理 Google OAuth 2.0 身份验证以访问您的日历数据。

自动身份验证流程（服务器启动期间）

1. 确保gcp-oauth.keys.json命名正确并放置在项目根目录中。
2. 启动 MCP 服务器： npm start 。
3. 服务器将检查.gcp-saved-tokens.json中是否存在有效的身份验证令牌。
4. 如果找到有效的令牌，服务器将正常启动。
5. 如果没有找到有效的令牌：
   • 服务器尝试启动临时本地 Web 服务器（尝试端口 3000-3004）。
   • 您的默认网络浏览器将自动打开 Google 帐户登录和同意屏幕。
   • 按照浏览器中的提示授权应用程序。
   • 授权成功后，您将被重定向到本地页面（例如， http://localhost:3000/oauth2callback ）。
   • 此页面将显示一条成功消息，确认令牌已保存到.gcp-saved-tokens.json （并显示确切的文件路径）。
   • 临时认证服务器自动关闭。
   • 主 MCP 服务器继续其启动过程。

手动身份验证流程

如果您需要重新进行身份验证或希望单独处理身份验证：

1. 运行命令： npm run auth
2. 该脚本执行上述相同的基于浏览器的身份验证流程。
3. 您的浏览器将打开，您授权后，您将看到指示令牌保存位置的成功页面。
4. 验证成功后，脚本将自动退出。

代币管理

• 身份验证令牌存储在项目根目录中的.gcp-saved-tokens.json中。
• 该文件是自动创建的，不应提交到版本控制（它包含在.gitignore中）。
• 服务器尝试使用存储的刷新令牌自动刷新过期的访问令牌。
• 如果刷新令牌本身过期（例如，如果 Google Cloud 应用处于测试模式，则在 7 天后）或被撤销，您将需要使用自动流程（通过重新启动服务器）或手动npm run auth命令重新进行身份验证。

测试

单元和集成测试是使用Vitest实现的。

• 运行测试： npm test
• 在监视模式下运行测试： npm run test:watch
• 生成覆盖率报告： npm run coverage

测试模拟外部依赖项（Google API、文件系统）以确保对服务器逻辑和处理程序进行隔离测试。

安全说明

• 服务器在本地运行并需要 OAuth 身份验证。
• OAuth 凭证 ( gcp-oauth.keys.json ) 和已保存的令牌 ( .gcp-saved-tokens.json )永远不应提交到版本控制中。请确保将它们添加到你的.gitignore文件中。
• 对于生产用途，请考虑让 Google 验证您的 OAuth 应用程序。

与 Claude Desktop 一起使用

1. 将此配置添加到您的 Claude Desktop 配置文件中。例如/Users/<user>/Library/Application Support/Claude/claude_desktop_config.json ：
   { "mcpServers": { "google-calendar": { "command": "node", "args": ["<absolute-path-to-project-folder>/build/index.js"] } } }
   注意：将<absolute-path-to-project-folder>替换为项目目录的实际路径。
2. 重启Claude桌面

发展

故障排除

1. 回调时身份验证错误/连接重置：
   • 确保gcp-oauth.keys.json存在并包含桌面应用程序类型的凭据。
   • 验证您的用户电子邮件是否已在 Google Cloud OAuth 同意屏幕设置中添加为测试用户（等待几分钟以使更改生效）。
   • 尝试删除.gcp-saved-tokens.json并重新验证（ npm run auth或重新启动npm start ）。
   • 检查在需要身份验证时没有其他进程阻塞端口 3000-3004。
2. 代币每周到期：
   • 如果您的 Google Cloud 应用处于测试模式，刷新令牌将在 7 天后过期。请根据需要重新进行身份验证。
   • 考虑将您的应用移至 Google Cloud Console 中的生产环境，以获得更长久的刷新令牌（需要 Google 验证）。
3. 构建错误：
   • 再次运行npm install 。
   • 检查 Node.js 版本（使用 LTS）。
   • 删除build/目录并运行npm run build 。

执照

麻省理工学院