Google Calendar MCP 服务器

🔔 版本更新通知 🔔 1.0.1 版本修复了 Node.js v20.9.0+ 与 'open' 包的兼容性问题，该包在 10+ 版本中现在仅支持 ESM。1.0.0 版本标志着我们的第一个生产就绪版本，具有全面的代码重构和国际化。

<a href="https://glama.ai/mcp/servers/@takumi0706/google-calendar-mcp"> <img width="380" height="200" src="https://glama.ai/mcp/servers/@takumi0706/google-calendar-mcp/badge" alt="image"/> </a>

项目概述

Google Calendar MCP 服务器是一个 MCP (模型上下文协议) 服务器实现，它支持 Google Calendar 和 Claude Desktop 之间的集成。该项目使 Claude 能够与用户的 Google Calendar 交互，从而能够通过自然语言交互显示、创建、更新和删除日历事件。

核心功能

• Google Calendar 集成: 提供 Claude Desktop 和 Google Calendar API 之间的桥梁
• MCP 实现: 遵循 AI 助手工具集成的模型上下文协议规范
• OAuth2 身份验证: 安全地处理 Google API 身份验证流程
• 事件管理: 支持全面的日历事件操作（获取、创建、更新、删除）
• 颜色支持: 能够使用 colorId 参数设置和更新事件颜色
• STDIO 传输: 使用标准输入/输出与 Claude Desktop 通信

技术架构

本项目使用：

• TypeScript: 用于类型安全的代码开发
• MCP SDK: 使用 @modelcontextprotocol/sdk 与 Claude Desktop 集成
• Google API: 使用 googleapis 访问 Google Calendar API
• Zod: 为请求/响应数据实现模式验证
• 基于环境的配置: 使用 dotenv 进行配置管理
• Helmet.js: 用于安全标头
• AES-256-GCM: 用于令牌加密
• Jest: 用于单元测试和覆盖率
• GitHub Actions: 用于 CI/CD

主要组件

1. MCP 服务器: 处理与 Claude Desktop 通信的核心服务器实现
2. Google Calendar 工具: 日历操作（检索、创建、更新、删除）
3. 身份验证处理程序: 管理与 Google API 的 OAuth2 流程
4. 模式验证: 确保所有操作中的数据完整性
5. 令牌管理器: 安全处理身份验证令牌

可用工具

此 MCP 服务器提供以下工具来与 Google Calendar 交互：

1. getEvents

检索具有各种过滤选项的日历事件。

参数：

• calendarId (可选): 日历 ID（如果省略，则使用主日历）
• timeMin (可选): 事件检索的开始时间（ISO 8601 格式，例如 "2025-03-01T00:00:00Z"）
• timeMax (可选): 事件检索的结束时间（ISO 8601 格式）
• maxResults (可选): 要检索的最大事件数（默认值：10）
• orderBy (可选): 排序顺序（"startTime" 或 "updated"）

2. createEvent

创建一个新的日历事件。

参数：

• calendarId (可选): 日历 ID（如果省略，则使用主日历）
• event: 包含事件详细信息的对象：
  • summary (必需): 事件标题
  • description (可选): 事件描述
  • location (可选): 事件位置
  • start: 具有以下内容的开始时间对象：
    • dateTime (可选): ISO 8601 格式（例如 "2025-03-15T09:00:00+09:00"）
    • date (可选): YYYY-MM-DD 格式，用于全天事件
    • timeZone (可选): 时区（例如 "Asia/Tokyo"）
  • end: 结束时间对象（与开始时间格式相同）
  • attendees (可选): 具有电子邮件和可选 displayName 的与会者数组
  • colorId (可选): 事件颜色 ID (1-11)

3. updateEvent

更新现有的日历事件。

参数：

• calendarId (可选): 日历 ID（如果省略，则使用主日历）
• eventId (必需): 要更新的事件的 ID
• event: 包含要更新的字段的事件详细信息对象（与 createEvent 结构相同，所有字段都是可选的）

4. deleteEvent

删除日历事件。

参数：

• calendarId (可选): 日历 ID（如果省略，则使用主日历）
• eventId (必需): 要删除的事件的 ID

开发指南

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

代码结构

• src/: 源代码目录
  • auth/: 身份验证处理
  • config/: 配置设置
  • mcp/: MCP 服务器实现
  • tools/: Google Calendar 工具实现
  • utils/: 实用程序函数和助手

最佳实践

• 根据 TypeScript 最佳实践进行适当的类型化
• 维护全面的错误处理
• 确保正确的身份验证流程
• 保持依赖项最新
• 为所有函数编写清晰的文档
• 实施安全最佳实践
• 遵循 OAuth 2.1 身份验证标准
• 对所有输入/输出数据使用模式验证

测试

• 为核心功能实现单元测试
• 彻底测试身份验证流程
• 验证针对 Google API 的日历操作
• 运行带有覆盖率报告的测试
• 确保包含安全测试

部署

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

npx @takumi0706/google-calendar-mcp@1.0.1

前提条件

1. 创建一个 Google Cloud 项目并启用 Google Calendar API
2. 在 Google Cloud Console 中配置 OAuth2 凭据
3. 设置环境变量：

# 使用您的 Google OAuth 凭据创建一个 .env 文件
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:4153/oauth2callback
# 可选：令牌加密密钥（如果未提供，则自动生成）
TOKEN_ENCRYPTION_KEY=32-byte-hex-key
# 可选：身份验证服务器端口和主机（默认端口：4153，主机：localhost）
AUTH_PORT=4153
AUTH_HOST=localhost
# 可选：MCP 服务器端口和主机（默认端口：3000，主机：localhost）
PORT=3000
HOST=localhost

Claude Desktop 配置

将服务器添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": [
        "-y",
        "@takumi0706/google-calendar-mcp"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_REDIRECT_URI": "http://localhost:4153/oauth2callback"
      }
    }
  }
}

安全注意事项

• OAuth 令牌 仅存储在内存中（不存储在基于文件的存储中）
• 敏感凭据 必须作为环境变量提供
• 使用 AES-256-GCM 进行令牌加密，以实现安全存储
• 具有显式 code_verifier 和 code_challenge 生成的 PKCE 实现
• 用于 CSRF 保护的状态参数验证
• 使用 Helmet.js 应用的安全标头
• 用于 API 端点保护的速率限制
• 使用 Zod 模式进行输入验证

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

维护

• 定期更新以保持与 Google Calendar API 的兼容性
• 版本更新记录在 README.md 中
• 日志存储在用户的 home 目录 ~/.google-calendar-mcp/logs/ 中

故障排除

如果您遇到任何问题：

1. 检查您的 home 目录中的日志，位于 ~/.google-calendar-mcp/logs/
2. 确保您的 Google OAuth 凭据已正确配置
3. 确保您具有足够的 Google Calendar API 访问权限
4. 验证您的 Claude Desktop 配置是否正确

常见错误

• JSON 解析错误：如果您看到类似 Unexpected non-whitespace character after JSON at position 4 (line 1 column 5) 的错误，通常是由于 JSON-RPC 消息格式错误。此问题已在 0.6.7 及更高版本中修复。如果您仍然遇到这些错误，请更新到最新版本。
• 身份验证错误：验证您的 Google OAuth 凭据
• 连接错误：确保只有一个服务器实例正在运行
• 断开连接问题：确保您的服务器正确处理 MCP 消息，而无需自定义 TCP 套接字

版本历史

1.0.1 版本变更

• 修复了与 Node.js v20.9.0+ 和 'open' 包 (v10+) 的兼容性问题
• 将静态导入替换为仅 ESM 'open' 包的动态导入
• 改进了 OAuth 身份验证期间浏览器打开的错误处理
• 增强了代码注释，以提高可维护性

1.0.0 版本变更

• 主要版本发布，标志着生产就绪
• 全面的代码重构，以提高可维护性
• 所有消息和注释的国际化（将日语翻译成英语）
• 增强了代码一致性和可读性
• 改进了错误消息，以提供更好的用户体验
• 更新了文档以反映项目的当前状态
• 标准化了整个代码库的编码风格

0.8.0 版本变更

• 增强了 OAuth 身份验证流程，以处理刷新令牌问题
• 添加了 prompt: 'consent' 参数，以强制 Google 显示同意屏幕并提供新的刷新令牌
• 修改了身份验证流程，以便在没有刷新令牌的情况下仅使用访问令牌
• 改进了令牌刷新逻辑，以处理没有刷新令牌或刷新令牌无效的情况
• 更新了令牌存储，以保存刷新的访问令牌，从而更好地进行令牌管理
• 修复了令牌刷新逻辑中潜在的无限循环

0.7.0 版本变更

• 修复了导致 "Cannot GET /oauth2callback" 错误的 OAuth 回调处理问题
• 添加了从 MCP 服务器到 OAuth 服务器的自动重定向，以进行回调处理
• 改进了与不同 OAuth 重定向 URI 配置的兼容性
• 增强了 OAuth 身份验证流程的错误处理
• 更新了文档以反映 OAuth 回调处理修复

0.6.9 版本变更

• 修复了导致重复身份验证请求的 OAuth 身份验证提示问题
• 改进了身份验证流程，以防止打开多个浏览器窗口
• 增强了令牌刷新机制，以正确处理过期的令牌
• 更新了文档以反映 OAuth 身份验证修复

0.6.8 版本变更

• 修复了运行多个实例时出现的端口冲突问题
• 改进了版本管理系统
• 增强了服务器启动和关闭过程
• 将依赖项更新到最新的兼容版本

0.6.7 版本变更

• 修复了在使用 MCP Inspector 时导致错误的严重 JSON 解析错误
• 改进了日志记录，以防止干扰 JSON-RPC 消息
• 增强了 STDIO 传输中的消息处理
• 改进了格式错误的 JSON 消息的错误处理
• 在使用 npm version 命令更新版本时，添加了自动 npm install 过程
• 更新了文档以反映 JSON 解析错误修复和自动 npm install 过程

0.6.6 版本变更

• 在 utils/json-parser.ts 中添加了专用的 JSON-RPC 消息解析实用程序
• 为 JSON 解析创建了全面的测试套件，以防止回归
• 实施了 10 个测试用例，涵盖各种格式错误的 JSON 场景
• 重构了 server.ts 以使用通用的 JSON 解析实用程序
• 提高了代码可维护性和可测试性

0.6.5 版本变更

• 完全重新设计了 JSON-RPC 消息处理，以解决解析错误
• 简化并改进了从消息中提取有效 JSON 的算法
• 修复了 "Unexpected non-whitespace character after JSON at position 4" 错误
• 增强了错误处理，并提供了更具描述性的错误消息
• 改进了日志记录，以实现更好的诊断和故障排除

0.6.4 版本变更

• 进一步改进了 JSON-RPC 消息处理，以更可靠地处理格式错误的消息
• 增强了 JSON 对象和数组提取的正则表达式模式，并具有非贪婪匹配
• 添加了平衡括号匹配算法，以查找 JSON 对象和数组的正确结尾
• 修复了正则表达式模式中的 ESLint 警告
• 改进了错误日志记录，以实现更好的诊断
• 更新了 package.json 和 server.ts 中的版本号

0.6.3 版本变更

• 修复了 JSON-RPC 消息处理，以更可靠地处理格式错误的消息
• 改进了 JSON 对象提取的正则表达式模式
• 添加了 JSON 解析的后备机制
• 更新了 server.ts 中的版本号以匹配 package.json

0.6.2 版本变更

• 实施了 HTML 清理，以防止跨站点脚本 (XSS) 漏洞
• 添加了 escapeHtml 实用程序函数，以安全地处理 HTML 响应中用户控制的数据
• 修复了 OAuth 错误处理中潜在的 XSS 漏洞
• 为 HTML 清理功能添加了全面的测试套件
• 提高了针对注入攻击的整体安全态势

0.6.1 版本变更

• 修复了记录器配置，以确保信息日志转到 stdout 而不是 stderr
• 更新了依赖项以解决过时的软件包警告
• 删除了不必要的 @types/helmet 依赖项
• 修复了 eslint 版本以与 @typescript-eslint 软件包兼容
• 提高了整体稳定性和兼容性

0.6.0 版本变更

• 版本升级以保持与最新依赖项的兼容性
• 在传输层实施了 OAuth 2.1 身份验证
• 添加了对多个请求的 JSON-RPC 批处理的支持
• 增强了 PKCE 实现，并具有显式 code_verifier 和 code_challenge 生成
• 改进了 CSRF 保护，并具有显式状态参数验证
• 修复了 TokenManager 清理计时器，以在测试完成时正确释放资源
• 改进了间隔计时器的处理，以防止潜在的内存泄漏
• 增强了资源管理，以提高应用程序稳定性
• 提高了整体稳定性和性能
• 提高了代码质量和可维护性

0.5.1 版本变更

• 修复了小错误并提高了稳定性
• 更新了文档

0.5.0 版本变更

• 添加了对日历事件的颜色支持，并带有 colorId 参数
• 增强了事件创建和更新功能
• 将 @modelcontextprotocol/sdk 从 1.7.0 更新到 1.8.0
• 将 googleapis 从 133.0.0 更新到 148.0.0
• 将 winston 从 3.11.0 更新到 3.17.0
• 将 zod 从 3.22.4 更新到 3.24.2
• 提高了稳定性以及与最新依赖项的兼容性

0.4.2 版本变更

• 改进了工具注册，以正确地向客户端公开工具详细信息
• 通过显式工具定义增强了服务器功能注册
• 修复了服务器初始化中的操作顺序
• 改进了代码文档和注释

0.4.1 版本变更

• 重构了代码架构，以提高可维护性
• 实施了 ToolsManager 类以封装工具定义
• 通过将功能从 server.ts 移动到 tools.ts 来改进了代码组织
• 删除了未使用的导入和类型定义
• 提高了代码质量和可读性

0.4.0 版本变更

• 实施了令牌加密系统 (AES-256-GCM)
• 添加了基本的 OAuth 身份验证流程增强功能
• 使用 Helmet.js 添加了安全标头
• 实施了速率限制以防止 DDoS 攻击
• 增强了输入验证和错误处理
• 提高了测试覆盖率
• 使用 GitHub Actions 实现了自动化 CI/CD
• 增强了安全文档

0.3.3 版本变更

• 删除了基于文件的令牌存储，并改进了内存中的令牌管理
• 修复了各种内存泄漏并改进了资源管理
• 提高了稳定性和错误处理

0.3.2 版本变更

• 添加了自动浏览器打开以进行 Google Calendar 授权
• 改进了身份验证流程中的用户体验

0.3.1 版本变更

• 更新了服务器版本指示器
• 修复了事件处理中的小错误

0.2.7 修复

• 修复了 JSON-RPC 消息处理以处理格式错误的消息
• 改进了客户端和服务器之间的消息处理，并具有更强大的解析功能
• 增强了日志记录格式，并提供了更好的上下文信息
• 添加了调试模式支持以进行 JSON-RPC 消息的故障排除

0.2.6 修复

• 修复了导致解析错误的 JSON-RPC 消息处理
• 删除了导致连接问题的自定义 TCP 套接字服务器
• 为传输错误添加了适当的错误处理
• 改进了客户端和服务器之间消息交换的日志记录

0.2.0 版本变更

• 更新为使用最新的 MCP SDK API (v1.8.0+)
• 从 Server 类迁移到现代 McpServer 类
• 通过正确类型的工具处理程序提高了类型安全性
• 修复了更新操作以正确处理部分事件更新
• 增强了错误处理，并提供了详细的错误消息
• 优化了处理日历操作时的性能
• 通过直接 API 调用简化了实现

开发

要为此项目做出贡献：

# 克隆存储库
git clone https://github.com/takumi0706/google-calendar-mcp.git
cd google-calendar-mcp

# 安装依赖项
npm install

# 在开发模式下运行
npm run dev

测试

要运行测试：

# 运行所有测试
npm test

# 运行带有覆盖率报告的测试
npm test -- --coverage

许可证

MIT