local-only server

The server can only run on the client’s local machine because it depends on local resources.

Integrations

Provides event management capabilities for Google Calendar, allowing retrieval, creation, updating, and deletion of calendar events through the Google Calendar API with OAuth2 authentication

Google 日历 MCP 服务器

🔔 版本更新通知 🔔
1.0.2 版修复了updateEvent函数，以便在执行部分更新时保留现有事件数据。1.0.1 版修复了 Node.js v20.9.0+ 与“open”包的兼容性问题，该包在 10+ 版中现已成为 ESM 专用包。1.0.0 版是我们第一个可用于生产的版本，其中包含全面的代码重构和国际化功能。

项目概述

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-DD
  - timeZone （可选）：时区（例如“亚洲/东京”）
- end ：结束时间对象（与开始格式相同）
- attendees （可选）：带有电子邮件和可选显示名称的与会者数组
- colorId （可选）：事件颜色ID（1-11）

3. 更新事件

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

参数：

calendarId （可选）：日历 ID（如果省略则使用主日历）
eventId （必需）：要更新的事件的 ID
event ：包含要更新的字段的事件详细信息对象（与 createEvent 相同的结构，所有字段都是可选的）
- 只有明确提供的字段才会更新
- 更新请求中未包含的字段将保留其现有值
- 这允许部分更新而不会丢失数据

4. 删除事件

删除日历事件。

参数：

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

开发指南

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

先决条件

创建 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

Claude桌面配置

将服务器添加到您的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 日历 API 的兼容性
版本更新记录在 README.md 中
日志存储在用户的主目录~/.google-calendar-mcp/logs/

故障排除

如果您遇到任何问题：

检查主目录中的日志~/.google-calendar-mcp/logs/
确保您的 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 凭据
连接错误：确保只有一个服务器实例正在运行
断开连接问题：确保您的服务器在没有自定义 TCP 套接字的情况下正确处理 MCP 消息

版本历史记录

版本 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

执照

麻省理工学院

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

一个将 Google 日历与 Claude Desktop 集成的模型上下文协议服务器，使用户能够通过自然语言管理日历事件（查看、创建、更新、删除）。

Google Calendar MCP Server

Integrations

Google 日历 MCP 服务器

项目概述

核心功能

技术架构

主要部件

可用工具

1. 获取事件

2. 创建事件

3. 更新事件

4. 删除事件

开发指南

代码结构

最佳实践

测试

部署

先决条件

Claude桌面配置

安全注意事项

维护

故障排除

常见错误

版本历史记录

版本 1.0.2 变更

版本 1.0.1 变更

版本 1.0.0 变更

版本 0.8.0 变更

发展

测试

执照

Appeared in Searches