星战科技xingzhan.cloud
返回市场
谷歌日历mcp

谷歌日历mcp

作者：takumi070653 星标更新：2025-10-22
安装使用来源：spider==github.com

项目介绍

Google Calendar MCP 服务器

Apr-15-2025 12-17-08

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

版本 许可证

日本語 English

项目概述

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

核心功能

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

技术架构

该项目使用：

  • TypeScript：用于类型安全的代码开发
  • MCP SDK：使用 @modelcontextprotocol/sdk 与 Claude 桌面集成
  • Google API：使用 googleapis 访问 Google 日历 API
  • Hono：轻量且快速的 Web 框架，用于认证服务器
  • OAuth2 提供者：使用 @hono/oauth-providers 实现 PKCE 启用的 OAuth2 流程
  • Zod：实现请求/响应数据的模式验证
  • 基于环境的配置：使用 dotenv 进行配置管理
  • AES-256-GCM：使用 Node.js 加密模块进行令牌加密
  • Open：在认证期间自动启动浏览器
  • Readline：在服务器环境中手动输入认证信息
  • Jest：用于单元测试和覆盖率
  • GitHub Actions：用于持续集成和持续部署

主要组件

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

可用工具

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

1. getEvents

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

参数：

  • calendarId（可选）：日历 ID（如果省略、为空字符串、null 或 undefined，则使用主要日历）
  • timeMin（可选）：事件检索的开始时间（ISO 8601 格式，例如 "2025-03-01T00:00:00Z"）。空字符串、null 或 undefined 值将被忽略
  • timeMax（可选）：事件检索的结束时间（ISO 8601 格式）。空字符串、null 或 undefined 值将被忽略
  • maxResults（可选）：要检索的最大事件数（默认值：10）
  • orderBy（可选）：排序顺序（"startTime" 或 "updated"）。如果为空字符串、null 或 undefined，默认为 "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 日历。当您想在不重启 Claude 的情况下切换不同的 Google 账户时，这很有用。

参数：

  • 无

开发指南

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

代码结构

  • src/：源代码目录
    • auth/：认证处理
    • config/：配置设置
    • mcp/：MCP 服务器实现
    • tools/：Google 日历工具实现
    • utils/：实用函数和辅助程序

最佳实践

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

测试

  • 为核心功能实现单元测试
  • 全面测试认证流程
  • 验证与 Google API 的日历操作
  • 运行带有覆盖率报告的测试
  • 确保包括安全测试

部署

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

npx @takumi0706/google-calendar-mcp@1.0.7

前提条件

  1. 创建一个 Google Cloud 项目并启用 Google 日历 API
  2. 在 Google Cloud 控制台中配置 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
# 可选：启用手动认证（在无法访问 localhost 的环境中非常有用）
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 对令牌进行加密以实现安全存储
  • 实现 PKCE，显式生成 code_verifier 和 code_challenge
  • 为 CSRF 保护验证 state 参数
  • 为 API 端点保护实施速率限制
  • 使用 Zod 模式进行输入验证

更多细节，请参阅 SECURITY.md。

维护

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

故障排除

如果您遇到任何问题：

  1. 确保您的 Google OAuth 凭据正确配置
  2. 确保您有足够的权限访问 Google 日历 API
  3. 验证您的 Claude 桌面配置是否正确

常见错误

  • 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 值。

版本历史

版本 1.0.7 更改

  • 增强了 MCP 工具的参数验证，以正确处理空字符串、null 和 undefined 值
  • 修复了当传递空字符串参数给 getEvents 工具时出现的 MCP 错误 -32602
  • 改进了 preprocessArgs 函数，跳过空值，使 Zod 模式默认值能正确应用
  • 增加了对空参数处理的全面测试覆盖

版本 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 的 'open' 包
  • 改进了 OAuth 认证期间浏览器打开的错误处理
  • 增强了代码注释，以提高可维护性

版本 1.0.0 更改

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

版本 0.8.0 更改

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

安装

快速启动（推荐）

直接从 npm 安装：

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

手动安装

用于开发或定制：

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

# 安装依赖项
npm install

# 构建项目
npm run build

# 运行服务器
npm start

生产部署

对于生产用途，服务器需要有效的 Google OAuth 凭据。没有正确的凭据，服务器将无法启动，确保符合安全合规性。

测试

要运行测试：

# 运行所有测试
npm test

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

许可证

MIT