Google Calendar

🚀 谷歌日历 MCP 服务器

本项目是一个使用 TypeScript 构建的 Model Context Protocol (MCP) 服务器，它集成了谷歌日历功能，能够帮助用户更便捷地管理谷歌日历。

🚀 快速开始

安装

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"]
      }
   }
}

✨ 主要特性

• 无缝谷歌日历集成：支持 OAuth 2.0 认证，实现与谷歌日历的无缝对接。
• 持久化令牌存储：实现自动认证，无需用户频繁操作。
• 日历管理：可列出并操作日历及其事件，方便用户管理日历信息。
• 事件全生命周期操作：支持创建、读取、更新和删除日历事件，满足各种使用场景。
• 按日期范围获取事件：能够查询指定时间内的日历事件，提高信息检索效率。
• 实时更新推送：支持 Server-Sent Events (SSE) 传输协议，及时推送日历事件的更新。
• 简单集成：兼容 Claude 和其他 MCP 兼容的 AI 助手，便于与其他系统集成。

📦 安装指南

npm install -g mcp-google-calendar

或直接运行：

npx -y mcp-google-calendar

💻 使用示例

基础用法

启动服务器

使用标准 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"]
      }
   }
}

高级用法

日历创建

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'
  }
});

📚 详细文档

功能模块

认证授权

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

日历管理

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

事件管理

1. 事件创建：创建新的日历事件。
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

🔧 技术细节

本项目使用 TypeScript 构建，借助 Node.js 运行环境，通过 OAuth 2.0 认证与谷歌日历 API 进行交互。在代码结构上，将不同功能模块进行了分离，如认证授权模块、日历管理模块和事件管理模块，提高了代码的可维护性和可扩展性。同时，支持 WebSocket 和 Server-Sent Events (SSE) 两种通信协议，以满足不同的使用场景。

📄 安全注意事项

⚠️ 重要提示

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