Google Calendar MCP 服务器

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

使用示例

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

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

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

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

2. 日历分析：

   我本周有哪些不是我日常安排的事件？
   

3. 检查出席情况：

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

4. 自动协调事件：

   这是某人提供给我的可用时间。
   查看可用时间，并在我的工作日历上创建一个空闲的事件。
   

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

   请查看我未来一周的个人和工作日历，提供可用时间。
   选择在东海岸正常工作时间内效果良好的时间。会议时间为 1 小时
   

要求

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

Google Cloud 设置

1. 转到 Google Cloud Console
2. 创建一个新项目或选择一个现有项目。
3. 为您的项目启用 Google Calendar 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 - 启动已编译的服务器（使用 node build/index.js）
• npm run dev - 使用 ts-node 在开发模式下启动服务器（监视更改）
• npm run auth - 手动启动 Google OAuth 流程的身份验证服务器（如果自动流程失败或用于测试，则很有用）
• npm test - 使用 Vitest 运行单元/集成测试套件
• npm run test:watch - 在监视模式下运行测试
• npm run coverage - 运行测试并生成覆盖率报告

身份验证

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

自动身份验证（推荐）

1. 将您的 Google OAuth 凭据放置在 gcp-oauth.keys.json 中。
2. 启动 MCP 服务器：npm start 或 npm run dev。
3. 如果在 .gcp-saved-tokens.json 中未找到有效的身份验证令牌，服务器将自动：
   • 启动身份验证服务器（默认情况下在端口 3000-3004 上）
   • 打开一个浏览器窗口进行 OAuth 流程
   • 身份验证后，将令牌安全地保存到 .gcp-saved-tokens.json
   • 关闭身份验证服务器
   • 继续正常的 MCP 服务器操作

服务器自动管理令牌刷新。

手动身份验证

运行 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 Desktop

开发

故障排除

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

   • 如果您的 Google Cloud 应用程序处于测试模式，则令牌每周过期。通过运行 npm run auth 或重新启动服务器来重新进行身份验证。

2. OAuth 令牌错误/身份验证失败

   • 确保 gcp-oauth.keys.json 存在于项目根目录中，并且包含有效的桌面应用程序凭据。
   • 尝试删除 .gcp-saved-tokens.json 并重新进行身份验证。
   • 检查 Google Cloud Console 以确保已启用 Calendar API，并且如果应用程序处于测试模式，则您的用户被列为测试用户。
   • 验证当身份验证服务器需要启动时，没有其他进程正在使用端口 3000-3004。

3. 构建错误

   • 再次运行 npm install。
   • 检查 Node.js 版本。
   • 删除 build/ 目录并运行 npm run build。

许可证

MIT