🚀 谷歌日历 MCP 服务器

本项目是一个使用 TypeScript 构建的 Model Context Protocol (MCP) 服务器，集成了谷歌日历功能，能为用户提供便捷的日历管理与操作体验。

🚀 快速开始

本服务器使用 TypeScript 构建，集成了谷歌日历功能，支持 OAuth 2.0 认证，可实现日历及事件的管理操作，还能通过 Server-Sent Events (SSE) 进行实时更新推送，并且兼容 Claude 和其他 MCP 兼容的 AI 助手。

✨ 主要特性

• 无缝谷歌日历集成：支持 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. 令牌刷新：实现令牌的自动刷新机制，确保长期有效访问

日历管理

基础用法

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

高级用法

• 日历读取：获取指定日历的详细信息，包括名称、描述等
• 日历更新：修改已存在的日历属性，例如更新日历名称或描述
• 日历删除：移除不再需要的日历

事件管理

基础用法

// 事件创建
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'
  }
});

高级用法

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

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

// 事件删除
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

🔧 技术细节

本项目使用 TypeScript 构建，借助谷歌日历 API 实现日历及事件的管理功能。通过 OAuth 2.0 进行认证授权，确保数据安全。采用 Server-Sent Events (SSE) 实现实时更新推送，提升用户体验。同时，项目结构清晰，各模块分工明确，便于开发和维护。

📄 许可证

文档未提及相关许可证信息。

⚠️ 重要提示

⚠️ 重要提示

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