Google Calendar MCP Server

Google Calendar MCP 服务

🔔 版本更新通知 🔔
版本 2.0.0 迁移至 MCP 协议修订版 2026-07-28，并在 OAuth 流程中实现 PKCE。 需要 Node.js 20 或更高版本。完整变更列表请参阅下方的版本历史。

项目概述

Google Calendar MCP 服务是一种 MCP（Model Context Protocol）服务实现，可将 Google Calendar 与 Claude Desktop 集成。该项目使 Claude 能够与用户的 Google Calendar 交互，通过自然语言交互来显示、创建、更新和删除日历事件。

核心功能

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

技术架构

本项目使用：

• TypeScript：用于开发类型安全的代码
• MCP SDK：使用 @modelcontextprotocol/server v2（协议修订版 2026-07-28，同时仍为较旧客户端提供 2025 修订版）
• Google API：使用 googleapis 访问 Google Calendar API
• Hono：轻量且快速的身份验证服务 Web 框架
• google-auth-library：通过 PKCE（S256）驱动 OAuth2 授权码流程
• Zod：用于实现请求/响应数据的架构验证
• 基于环境变量的配置：使用 dotenv 管理配置
• AES-256-GCM：使用 Node.js crypto 模块加密令牌
• Open：在身份验证期间自动启动浏览器
• Readline：在服务端环境中手动输入身份验证信息
• 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（如果省略、为空字符串、为 null 或未定义，则使用主日历）
• timeMin（可选）：检索事件的开始时间（ISO 8601 格式，例如 "2025-03-01T00:00:00Z"）。空字符串、null 或未定义的值将被忽略
• timeMax（可选）：检索事件的结束时间（ISO 8601 格式）。空字符串、null 或未定义的值将被忽略
• maxResults（可选）：要检索的最大事件数（默认值：10）
• orderBy（可选）：排序顺序（"startTime" 或 "updated"）。如果为空字符串、null 或未定义，则默认为 "startTime"

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（可选）：参会者数组，包含电子邮件地址和可选的显示名称
  • 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/：身份验证处理（使用 PKCE 的 OAuth 流程、令牌存储）
  • calendar/：Google Calendar API 集成
  • config/：配置设置和验证
  • mcp/：MCP 服务实现
    • tools/：Google Calendar 工具处理程序
  • utils/：实用函数和辅助工具

最佳实践

• 遵循 TypeScript 最佳实践进行恰当的类型定义
• 保持完善的错误处理
• 确保身份验证流程正确
• 保持依赖项为最新版本
• 为所有函数编写清晰的文档
• 落实安全最佳实践
• 遵循 OAuth 2.1 身份验证标准
• 对所有输入/输出数据进行架构验证

测试

• 为核心功能编写单元测试
• 全面测试身份验证流程
• 根据 Google API 验证日历操作
• 运行测试并生成覆盖率报告
• 确保包含安全测试

部署

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

npx @takumi0706/[email protected]

先决条件

0. Node.js 20 或更高版本
1. 创建 Google Cloud 项目并启用 Google Calendar API
2. 在 Google Cloud Console 中配置 OAuth2 凭据
3. 设置环境变量：

# 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 Desktop 配置

将服务添加到你的 claude_desktop_config.json。如果你运行的环境无法访问 localhost，请添加值为 "true" 的 USE_MANUAL_AUTH 环境变量。

{
  "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（S256），每次请求都会生成一个 code_verifier，且绝不会将其发送到授权端点
• 状态参数验证用于防范 CSRF：使用 256 位 CSPRNG 状态值，以恒定时间进行比较，且只能使用一次，并在 10 分钟后过期
• 固定重定向 URI：从配置中获取，而非使用请求的 Host 标头
• 使用 Zod 架构进行输入验证
• 对插入 OAuth 结果页面的所有值进行 HTML 转义

详情请参阅 SECURITY.md。

维护

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

故障排除

如果遇到任何问题：

1. 确认 Google OAuth 凭据配置正确
2. 确保拥有访问 Google Calendar 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 并重启应用程序。
• 连接错误：确保只运行一个服务实例
• 断开连接问题：确保服务能够正确处理 MCP 消息，而不使用自定义 TCP 套接字
• 无法访问 localhost：如果运行应用程序的环境无法访问 localhost（例如远程服务或容器），请设置 USE_MANUAL_AUTH=true 以启用手动身份验证。授权应用程序后，您可以手动输入 Google 显示的授权码。
• MCP 参数验证错误：如果看到错误 -32602，且字符串参数为空，请更新到 1.0.7 或更高版本；该版本能够正确处理空字符串、null 和 undefined 值。

版本历史

版本 2.0.0 变更

安全性

• 在 OAuth 授权码流程中实现了 PKCE（S256）。早期版本虽有 PKCE 文档，但从未发送 code_challenge。
• state 参数现在是 256 位 CSPRNG 值，采用恒定时间比较、仅可使用一次，并在 10 分钟后过期。此前它是用 Math.random() 生成的。
• 修复了 OAuth 错误页面中的反射型 XSS：现在会记录错误详情，而不将其插入 HTML；所有插入的值也都会经过转义。
• redirect_uri 现在固定为配置值，而不是根据请求的 Host 标头生成。
• 本地授权服务现在会在端口已被占用时中止，而不再假定有其他实例正在处理该流程。
• TOKEN_ENCRYPTION_KEY 现在必须恰好包含 64 个十六进制字符；启动时会拒绝无效密钥和全零密钥。
• 已解决生产依赖项中所有已知漏洞。

协议

• 已迁移至 @modelcontextprotocol/server v2 和协议修订版 2026-07-28。仍支持 2025 年的修订版，因此现有客户端可以继续使用。
• tools/list 现在会公布真实的架构，因此 createEvent 的 event 参数等嵌套对象会公开其属性。此前这些对象是不透明的。
• 现在已实现 prompts/get。服务此前公布了十个无法获取的提示词。
• resources/read 现在会返回规范要求的结构。
• initialize 不再通过 capabilities 泄露 Zod 内部信息。

重大变更

• 需要 Node.js 20 或更高版本。

其他

• 已将工具链迁移至 pnpm，升级了 googleapis、hono 和 zod，并移除了 @hono/oauth-providers。
• 已从发布代码中移除 any 和类型断言，并通过 lint 强制执行。

版本 1.0.7 变更

• 增强了 MCP 工具的参数验证，以妥善处理空字符串、null 和 undefined 值
• 修复了向 getEvents 工具传入空字符串参数时出现的 MCP 错误 -32602
• 改进了 preprocessArgs 函数，使其跳过空值，从而正确应用 Zod 架构默认值
• 增加了全面的测试覆盖，验证对空参数的处理

版本 1.0.6 变更

• 修复了此 Google Calendar MCP 服务不需要 scope 的问题

版本 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 显示授权同意屏幕并提供新的刷新令牌
• 修改身份验证流程，使其在没有刷新令牌时也能仅凭访问令牌运行
• 改进令牌刷新逻辑，以处理没有刷新令牌或刷新令牌无效的情况
• 更新令牌存储逻辑，保存刷新的访问令牌，以便更好地管理令牌
• 修复令牌刷新逻辑中可能出现的无限循环问题

安装

快速开始（推荐）

直接从 npm 安装：

npm install -g @takumi0706/google-calendar-mcp

手动安装

用于开发或自定义：

# Clone the repository
git clone https://github.com/takumi0706/google-calendar-mcp.git
cd google-calendar-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run the server
npm start

生产环境部署

在生产环境中使用时，服务需要有效的 Google OAuth 凭据。若未配置正确的凭据，服务将无法启动，以确保符合安全要求。

测试

运行测试：

# Run all tests
npm test

# Run tests with coverage report
npm test -- --coverage

许可证

MIT