Google 日历 MCP 服务器

🔔 版本更新通知 🔔
1.0.5 版本新增了对重复事件的支持，通过createEvent和updateEvent工具中的recurrence参数即可实现。这样一来，您可以直接创建和修改重复事件，而无需在创建后手动设置。

项目概述

Google 日历 MCP 服务器是一个 MCP（模型上下文协议）服务器实现，可实现 Google 日历与 Claude 桌面的集成。该项目使 Claude 能够与用户的 Google 日历进行交互，并通过自然语言交互提供显示、创建、更新和删除日历事件的功能。

核心功能

• Google 日历集成：在 Claude Desktop 和 Google 日历 API 之间架起桥梁

• MCP 实现：遵循模型上下文协议规范，用于 AI 辅助工具集成

• OAuth2 身份验证：安全地处理 Google API 身份验证流程

• 事件管理：支持全面的日历事件操作（获取、创建、更新、删除）

• 颜色支持：能够使用 colorId 参数设置和更新事件颜色

• STDIO 传输：使用标准输入/输出与 Claude Desktop 进行通信

Related MCP server: Calendar Tools MCP Server

技术架构

该项目使用：

• TypeScript ：用于类型安全的代码开发

• MCP SDK ：使用@modelcontextprotocol/sdk与Claude Desktop集成

• Google API ：使用googleapis访问 Google 日历 API

• Zod ：实现请求/响应数据的模式验证

• 基于环境的配置：使用 dotenv 进行配置管理

• Helmet.js ：用于安全标头

• AES-256-GCM ：用于令牌加密

• Jest ：用于单元测试和覆盖率

• GitHub Actions ：用于 CI/CD

主要部件

1. MCP 服务器：处理与 Claude Desktop 通信的核心服务器实现

2. Google 日历工具：日历操作（检索、创建、更新、删除）

3. 身份验证处理程序：使用 Google API 管理 OAuth2 流程

4. 模式验证：确保所有操作中的数据完整性

5. 令牌管理器：安全处理身份验证令牌

可用工具

此 MCP 服务器提供以下与 Google 日历交互的工具：

1. 获取事件

使用各种过滤选项检索日历事件。

参数：

• calendarId （可选）：日历 ID（如果省略则使用主日历）

• timeMin （可选）：事件检索的开始时间（ISO 8601 格式，例如“2025-03-01T00:00:00Z”）

• timeMax （可选）：事件检索的结束时间（ISO 8601 格式）

• maxResults （可选）：要检索的最大事件数（默认值：10）

• orderBy （可选）：排序顺序（“startTime”或“updated”）

2. 创建事件

创建一个新的日历事件。

参数：

• calendarId （可选）：日历 ID（如果省略则使用主日历）

• event ：事件详细信息对象，包含：

  • summary （必填）：活动标题

  • description （可选）：事件描述

  • location （可选）：活动地点

  • start ：开始时间对象：

    • dateTime （可选）：ISO 8601 格式（例如，“2025-03-15T09：00：00 + 09：00”）

    • date （可选）：全天活动的格式为 YYYY-MM-DD

    • timeZone （可选）：时区（例如“亚洲/东京”）

  • end ：结束时间对象（与开始格式相同）

  • attendees （可选）：带有电子邮件和可选显示名称的与会者数组

  • colorId （可选）：事件颜色ID（1-11）

  • recurrence （可选）：RFC5545 格式的重复规则数组（例如，[“RRULE：FREQ=WEEKLY;BYDAY=MO,WE,FR”]）

3. 更新事件

更新现有日历事件。该函数首先获取现有事件数据，然后将其与更新数据合并，并保留更新请求中未包含的字段。

参数：

• calendarId （可选）：日历 ID（如果省略则使用主日历）

• eventId （必需）：要更新的事件的 ID

• event ：包含要更新的字段的事件详细信息对象（与 createEvent 相同的结构，所有字段都是可选的）

  • 只有明确提供的字段才会更新

  • 更新请求中未包含的字段将保留其现有值

  • 这允许部分更新而不会丢失数据

  • 可以更新recurrence参数来修改重复事件模式

4. 删除事件

删除日历事件。

参数：

• calendarId （可选）：日历 ID（如果省略则使用主日历）

• eventId （必需）：要删除的事件的 ID

5. 认证

使用 Google 日历重新验证身份。当您想在不同的 Google 帐户之间切换而无需重启 Claude 时，此功能非常有用。

参数：

• 没有任何

开发指南

添加新功能、修改代码或修复错误时，请使用npm version命令语义化地增加每次更改的版本号。此外，请确保您的代码清晰易懂，并遵循所有必要的编码规则，例如面向对象编程 (OOP)。版本脚本会在版本更新时自动运行npm install ，但您仍应在提交代码之前构建、运行 lint 并测试代码。

代码结构

• src/ ：源代码目录

  • auth/ ：身份验证处理

  • config/ ：配置设置

  • mcp/ ：MCP 服务器实现

  • tools/ ：Google 日历工具实现

  • utils/ ：实用函数和助手

最佳实践

• 根据 TypeScript 最佳实践进行正确输入

• 维护全面的错误处理

• 确保正确的身份验证流程

• 保持依赖项最新

• 为所有功能编写清晰的文档

• 实施安全最佳实践

• 遵循 OAuth 2.1 身份验证标准

• 对所有输入/输出数据使用架构验证

测试

• 实施核心功能的单元测试

• 彻底测试身份验证流程

• 验证针对 Google API 的日历操作

• 使用覆盖率报告运行测试

• 确保包含安全测试

部署

该软件包在 npm 上发布为@takumi0706/google-calendar-mcp ：

先决条件

1. 创建 Google Cloud 项目并启用 Google 日历 API

2. 在 Google Cloud Console 中配置 OAuth2 凭据

3. 设置环境变量：

Claude桌面配置

将服务器添加到claude_desktop_config.json文件中。如果您在无法访问 localhost 的环境中运行，请将USE_MANUAL_AUTH环境变量设置为“true”。

安全注意事项

• OAuth 令牌仅存储在内存中（不存储在基于文件的存储中）

• 敏感凭据必须作为环境变量提供

• 使用 AES-256-GCM 进行令牌加密以实现安全存储

• 具有显式 code_verifier 和 code_challenge 生成的PKCE 实现

• 状态参数验证以进行 CSRF 保护

• 使用 Helmet.js 应用的安全标头

• API 端点保护的速率限制

• 使用 Zod 模式进行输入验证

有关更多详细信息，请参阅SECURITY.md 。

维护

• 定期更新以保持与 Google 日历 API 的兼容性

• 版本更新记录在 README.md 中

故障排除

如果您遇到任何问题：

1. 确保您的 Google OAuth 凭据已正确配置

2. 确保您拥有足够的权限来访问 Google 日历 API

3. 验证您的 Claude Desktop 配置是否正确

常见错误

• JSON 解析错误：如果您看到类似Unexpected non-whitespace character after JSON at position 4 (line 1 column 5)之类的错误，通常是由于 JSON-RPC 消息格式错误造成的。此问题已在 0.6.7 及更高版本中修复。如果您仍然遇到这些错误，请更新到最新版本。

• 身份验证错误：验证您的 Google OAuth 凭据

• 状态参数无效：如果您在重新Authentication failed: Invalid state parameter ，请更新至 1.0.3 或更高版本，该版本已修复 OAuth 服务器生命周期管理问题。在旧版本中，您可能需要关闭 4153 端口并重启应用程序。

• 连接错误：确保只有一个服务器实例正在运行

• 断开连接问题：确保您的服务器在没有自定义 TCP 套接字的情况下正确处理 MCP 消息

• 无法访问 localhost ：如果您在无法访问 localhost 的环境中运行应用程序（例如远程服务器或容器），请通过设置USE_MANUAL_AUTH=true启用手动身份验证。这将允许您在授权应用程序后手动输入 Google 显示的授权码。

版本历史记录

版本 1.0.6 变更

• 修复了此 google 日历 mcp 服务器中不需要范围的问题

版本 1.0.5 变更

• 通过createEvent和updateEvent工具中的recurrence参数添加了对重复事件的支持

• 允许直接创建和修改重复事件，无需手动设置

版本 1.0.4 变更

• 维护版本，版本号更新

• 与 1.0.3 版相比没有功能变化

• 确保与最新依赖项的兼容性

版本 1.0.3 变更

• 添加了新的authenticate工具，允许在不重新启动 Claude 的情况下重新进行身份验证

• 可以在会话期间切换不同的 Google 帐户

• 通过 MCP 接口公开身份验证功能

• 无需重新启动即可切换帐户，从而增强用户体验

• 为无法访问 localhost 的环境添加了手动身份验证选项

• 实现了 readline 接口，用于手动输入授权码

• 添加了 USE_MANUAL_AUTH 环境变量以启用手动身份验证

• 将 zod 依赖项更新至最新版本（3.24.2）

• 使用最新的 zod 功能改进了架构验证

• 增强代码稳定性和安全性

• 修复重新认证期间的“无效状态参数”错误

• 修改 OAuth 服务器以按需启动并在身份验证后关闭

• 改进服务器生命周期管理以防止端口冲突

• 增强身份验证流程的错误处理

版本 1.0.2 变更

• 修复了updateEvent函数以在执行部分更新时保留现有事件数据

• 添加了getEvent函数，用于在更新之前获取现有事件数据

• 修改updateEvent ，将更新数据与现有数据合并，以防止数据丢失

• 更新了架构验证，使更新请求中的所有字段都可选

• 改进了updateEvent函数的文档

版本 1.0.1 变更

• 修复了与 Node.js v20.9.0+ 和“open”包（v10+）的兼容性问题

• 将仅限 ESM 的“开放”包的静态导入替换为动态导入

• 改进了 OAuth 身份验证期间打开浏览器的错误处理

• 增强代码注释以提高可维护性

版本 1.0.0 变更

• 主要版本发布标志着生产准备就绪

• 全面重构代码以提高可维护性

• 所有消息和评论的国际化（日语翻译成英语）

• 增强代码一致性和可读性

• 改进错误消息以获得更好的用户体验

• 更新文档以反映项目的当前状态

• 整个代码库的标准化编码风格

版本 0.8.0 变更

• 增强 OAuth 身份验证流程以处理刷新令牌问题

• 添加了prompt: 'consent'参数，强制 Google 显示同意屏幕并提供新的刷新令牌

• 修改身份验证流程，如果刷新令牌不可用，则仅使用访问令牌

• 改进了令牌刷新逻辑，以处理没有刷新令牌或刷新令牌无效的情况

• 更新了令牌存储以保存刷新的访问令牌，从而实现更好的令牌管理

• 修复了令牌刷新逻辑中潜在的无限循环

发展

为该项目做出贡献：

测试

运行测试：

执照

麻省理工学院