Google Calendar MCP 服务器

Apr-15-2025 12-17-08

🔔 版本更新通知 🔔
版本 1.0.5 在 createEvent 和 updateEvent 工具中通过 recurrence 参数添加了对重复事件的支持。这使您能够直接创建和修改重复事件，而无需在创建后手动设置。

许可证

项目概述

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

主要组件

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

可用工具

该 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）
- recurrence（可选）：RFC5545 格式的重复规则数组（例如 ["RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR"]）

3. updateEvent

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

参数：

calendarId（可选）：日历 ID（如果省略则使用主日历）
eventId（必需）：要更新的事件 ID
event：事件详细信息对象，包含要更新的字段（与 createEvent 相同的结构，所有字段可选）
- 仅显式提供的字段将被更新
- 未包含在更新请求中的字段将保留其现有值
- 这允许在不丢失数据的情况下进行部分更新
- recurrence 参数可以更新以修改重复事件模式

4. deleteEvent

删除日历事件。

参数：

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

5. authenticate

重新认证 Google Calendar。这在您希望在不重启 Claude 的情况下切换不同 Google 账户时非常有用。

参数：

开发指南

在添加新功能、修改代码或修复错误时，请使用 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.5

先决条件

创建 Google Cloud 项目并启用 Google Calendar API
在 Google Cloud 控制台中配置 OAuth2 凭证
设置环境变量：

# 使用您的 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
# 可选：启用手动认证（在 localhost 不可访问时有用）
USE_MANUAL_AUTH=true

Claude Desktop 配置

将服务器添加到您的 claude_desktop_config.json 中。如果您在 localhost 不可访问的环境中运行，请添加 USE_MANUAL_AUTH 环境变量并将其设置为 "true"。

{
  "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 进行安全存储
PKCE 实现 使用显式的 code_verifier 和 code_challenge 生成
状态参数验证 用于 CSRF 保护
安全头 使用 Helmet.js 应用
速率限制 用于 API 端点保护
输入验证 使用 Zod 模式

更多详情，请参阅 SECURITY.md。

维护

定期更新以保持与 Google Calendar API 的兼容性
版本更新记录在 README.md 中

故障排除

如果遇到任何问题：

确保您的 Google OAuth 凭证配置正确
确保您具有足够的权限访问 Google Calendar API
验证您的 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 并重新启动应用程序。
连接错误：确保只有一个服务器实例在运行
断开连接问题：确保您的服务器正确处理 MCP 消息，而不使用自定义 TCP 套接字
无法访问 localhost：如果您在 localhost 不可访问的环境中运行应用程序（如远程服务器或容器），请通过设置 USE_MANUAL_AUTH=true 启用手动认证。这将允许您在授权应用程序后手动输入 Google 显示的授权代码。

版本历史

版本 1.0.6 更改

修复了该 Google Calendar 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 功能增强了模式验证
增强了代码的稳定性和安全性
修复了重新认证期间的 "Invalid state parameter" 错误
修改了 OAuth 服务器以按需启动并在认证后关闭
改进了服务器生命周期管理，以防止端口冲突
增强了认证流程的错误处理

版本 1.0.2 更改

修复了 updateEvent 函数，在执行部分更新时保留现有事件数据
添加了 getEvent 函数以在更新前获取现有事件数据
修改了 updateEvent 以将更新数据与现有数据合并，防止数据丢失
更新了模式验证，使更新请求中的所有字段可选
改进了 updateEvent 函数的文档

版本 1.0.1 更改

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

版本 1.0.0 更改

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

版本 0.8.0 更改

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

开发

要贡献到此项目：

# 克隆仓库
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

Google Calendar MCP 服务器

项目概述

核心功能

技术架构

主要组件

可用工具

1. getEvents

2. createEvent

3. updateEvent

4. deleteEvent

5. authenticate

开发指南

代码结构

最佳实践

测试

部署

先决条件

Claude Desktop 配置

安全考虑

维护

故障排除

常见错误

版本历史

版本 1.0.6 更改

版本 1.0.5 更改

版本 1.0.4 更改

版本 1.0.3 更改

版本 1.0.2 更改

版本 1.0.1 更改

版本 1.0.0 更改

版本 0.8.0 更改

开发

测试

许可证

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐