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 进行通信
技术架构
该项目使用：
- TypeScript ：用于类型安全的代码开发
- MCP SDK ：使用
@modelcontextprotocol/sdk与Claude Desktop集成 - Google API ：使用
googleapis访问 Google 日历 API - Zod ：实现请求/响应数据的模式验证
- 基于环境的配置：使用 dotenv 进行配置管理
- Helmet.js ：用于安全标头
- AES-256-GCM ：用于令牌加密
- Jest ：用于单元测试和覆盖率
- GitHub Actions ：用于 CI/CD
主要部件
- MCP 服务器：处理与 Claude Desktop 通信的核心服务器实现
- Google 日历工具：日历操作（检索、创建、更新、删除）
- 身份验证处理程序：使用 Google API 管理 OAuth2 流程
- 模式验证：确保所有操作中的数据完整性
- 令牌管理器：安全处理身份验证令牌
可用工具
此 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-DDtimeZone （可选）：时区（例如“亚洲/东京”）
end ：结束时间对象（与开始格式相同）attendees （可选）：带有电子邮件和可选显示名称的与会者数组colorId （可选）：事件颜色ID（1-11）recurrence （可选）：RFC5545 格式的重复规则数组（例如，[“RRULE：FREQ=WEEKLY;BYDAY=MO,WE,FR”]）
3. 更新事件
更新现有日历事件。该函数首先获取现有事件数据，然后将其与更新数据合并，并保留更新请求中未包含的字段。
参数：
calendarId （可选）：日历 ID（如果省略则使用主日历）eventId （必需）：要更新的事件的 IDevent ：包含要更新的字段的事件详细信息对象（与 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 ：
npx @takumi0706/google-calendar-mcp@1.0.5
先决条件
- 创建 Google Cloud 项目并启用 Google 日历 API
- 在 Google Cloud Console 中配置 OAuth2 凭据
- 设置环境变量：
# Create a .env file with your Google OAuth credentials
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REDIRECT_URI=http://localhost:4153/oauth2callback
# Optional: Token encryption key (auto-generated if not provided)
TOKEN_ENCRYPTION_KEY=32-byte-hex-key
# Optional: Auth server port and host (default port: 4153, host: localhost)
AUTH_PORT=4153
AUTH_HOST=localhost
# Optional: MCP server port and host (default port: 3000, host: localhost)
PORT=3000
HOST=localhost
# Optional: Enable manual authentication (useful when localhost is not accessible)
USE_MANUAL_AUTH=true
Claude桌面配置
将服务器添加到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 进行令牌加密以实现安全存储
- 具有显式 code_verifier 和 code_challenge 生成的PKCE 实现
- 状态参数验证以进行 CSRF 保护
- 使用 Helmet.js 应用的安全标头
- API 端点保护的速率限制
- 使用 Zod 模式进行输入验证
有关更多详细信息，请参阅SECURITY.md 。
维护
- 定期更新以保持与 Google 日历 API 的兼容性
- 版本更新记录在 README.md 中
故障排除
如果您遇到任何问题：
- 确保您的 Google OAuth 凭据已正确配置
- 确保您拥有足够的权限来访问 Google 日历 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 端口并重启应用程序。 - 连接错误：确保只有一个服务器实例正在运行
- 断开连接问题：确保您的服务器在没有自定义 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 显示同意屏幕并提供新的刷新令牌 - 修改身份验证流程，如果刷新令牌不可用，则仅使用访问令牌
- 改进了令牌刷新逻辑，以处理没有刷新令牌或刷新令牌无效的情况
- 更新了令牌存储以保存刷新的访问令牌，从而实现更好的令牌管理
- 修复了令牌刷新逻辑中潜在的无限循环
发展
为该项目做出贡献：
# Clone the repository
git clone https://github.com/takumi0706/google-calendar-mcp.git
cd google-calendar-mcp
# Install dependencies
npm install
# Run in development mode
npm run dev
测试
运行测试：
# Run all tests
npm test
# Run tests with coverage report
npm test -- --coverage
执照
麻省理工学院