谷歌日历 MCP 服务器

一个使用 TypeScript 构建的 Model Context Protocol (MCP) 服务器，集成谷歌日历功能。

功能特点

• 无缝谷歌日历集成：支持 OAuth 2.0 认证
• 持久化令牌存储：实现自动认证
• 日历管理：列出并操作日历及其事件
• 事件全生命周期操作：创建、读取、更新和删除日历事件
• 按日期范围获取事件：查询指定时间内的日历事件
• 实时更新推送：支持 Server-Sent Events (SSE) 传输协议
• 简单集成：兼容 Claude 和其他 MCP 兼容的 AI 助手

安装指南

npm install -g mcp-google-calendar

或直接运行：

npx -y mcp-google-calendar

先决条件

1. Node.js（v16 或更高版本）
2. 谷歌云平台账户
3. 谷歌日历 API 已启用
4. OAuth 2.0 凭证配置完成

配置指南

1. 谷歌云平台配置

1. 访问 谷歌云控制台
2. 创建新项目或选择现有项目
3. 启用谷歌日历 API：
   • 进入 "APIs & Services" > "Library"
   • 搜索 "Google Calendar API"
   • 点击 "Enable"
4. 配置 OAuth 一致性界面：
   • 访问 "APIs & Services" > "OAuth consent screen"
   • 选择 "External" 用户类型（或 "Internal" 对于谷歌Workspace）
   • 填写所需信息：
     • 应用名称：mcp-calendar
     • 用户支持邮箱：(你的邮箱)
     • 开发者联系方式：(你的邮箱)
   • 添加权限范围：
     • 点击 "Add or Remove Scopes"
     • 找到并选择 "https://www.googleapis.com/auth/calendar.events"
     • 将你的邮箱添加为测试用户
   • 完成设置流程
5. 创建 OAuth 凭证：
   • 进入 "Credentials" 部分
   • 点击 "Create Credentials" > "OAuth Client ID"
   • 选择应用类型为 "Desktop app"
   • 命名（例如：MCP Calendar Desktop Client）
   • 下载 JSON 文件并保存至项目目录下的 credentials.json

2. 环境配置

在项目根目录创建一个 .env 文件：

# 服务器配置
PORT=3420

# 谷歌日历 API 配置
CREDENTIALS_PATH=./credentials.json

使用方法

启动服务器

使用标准 WebSocket 运行：

npx -y mcp-google-calendar

使用 Server-Sent Events (SSE) 运行：

npx -y mcp-google-calendar --sse

集成 Claude Desktop

在 claude_desktop_config.json 中添加如下配置：

{
   "mcpServers": {
      "mcp-google-calendar": {
         "command": "npx",
         "args": ["-y", "mcp-google-calendar"]
      }
   }
}

功能模块

认证授权

1. 获取授权码：通过 OAuth 2.0 获取访问令牌所需的授权码
2. 令牌刷新：实现令牌的自动刷新机制，确保长期有效访问

日历管理

1. 日历创建：

   const calendar = await createCalendar({
     summary: 'My New Calendar',
     description: 'This is a new calendar created via API'
   });
   

2. 日历读取：获取指定日历的详细信息，包括名称、描述等

3. 日历更新：修改已存在的日历属性，例如更新日历名称或描述

4. 日历删除：移除不再需要的日历

事件管理

1. 事件创建：

   const event = await createEvent({
     calendarId: 'primary',
     summary: 'Meeting with Team',
     description: 'Discuss Q4 project plan',
     start: {
       timeZone: 'Asia/Shanghai',
       dateTime: '2023-10-05T09:00:00'
     },
     end: {
       timeZone: 'Asia/Shanghai',
       dateTime: '2023-10-05T10:30:00'
     }
   });
   

2. 事件查询：

   const events = await listEvents({
     calendarId: 'primary',
     timeMin: '2023-10-01T00:00:00',
     timeMax: '2023-10-31T23:59:59'
   });
   

3. 事件更新：

   const updatedEvent = await updateEvent({
     calendarId: 'primary',
     eventId: 'event_id_123',
     summary: 'Updated Meeting'
   });
   

4. 事件删除：

   await deleteEvent({
     calendarId: 'primary',
     eventId: 'event_id_123'
   });
   

实时推送

通过 SSE 实现事件的实时更新通知，订阅特定日历的所有事件变更。

开发信息

项目结构

src/
├── index.ts          # 入口文件
├── calendar.ts       # 日历管理模块
├── event.ts          # 事件管理模块
└── auth.ts           # 认证授权模块

快速上手

1. 安装依赖：

   npm install @types/googleapis google-auth-library
   

2. 初始化项目：

   npx tsinit
   

3. 编写代码并运行：

   npm run dev
   

安全注意事项

1. 凭证管理：确保 credentials.json 文件的安全性，避免泄露敏感信息
2. 权限控制：严格限制 API 调用的权限范围，防止越权操作
3. 日志监控：实时监控 API 请求和响应，及时发现异常行为
4. 错误处理：针对不同的 API 错误码和异常情况，设计完善的容错机制